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What you need to know about this 
book 


This book is about ECMAScript 6 (whose official name is ECMAScript 2015), a new version of 
JavaScript. 


Audience: JavaScript programmers 


In order to understand this book, you should already know JavaScript. If you don’t: my other book 
“Speaking JavaScript'” is free online and teaches programmers all of JavaScript (up to and including 
ECMAScript 5). 


Why should | read this book? 


This book covers ECMAScript 6 in great detail, but is structured so that you can also quickly get an 
overview if you want to. It not only tells you how ES6 works, it also tells you why it works the way 
it does. 


How to read this book 


This book has a lot of content, but its structure makes it easy to adjust the level of detail that you 
are confronted with. There are three levels of detail: 


e Quick start: Begin with the chapter “First steps with ECMAScript 6”. Additionally, almost 
every chapter starts with a section giving an overview of what's in the chapter. 

e Solid foundation: Each chapter always starts with the essentials and then increasingly goes 
into details. The headings should give you a good idea of when to stop reading, but I also 
occasionally give tips in sidebars w.r.t. how important it is to know something. 

e In-depth knowledge: Read all of a chapter, including the in-depth parts. 


Other things to know: 


*http://speakingjs.com/ 


What you need to know about this book ii 


e Recommendations: I occasionally recommend simple rules. Those are meant as guidelines, 
to keep you safe without you having to know (or remember) all of the details. I tend to favor 
mainstream over elegance, because most code doesn’t exist in a vacuum. However, I'll always 
give you enough information so that you can make up your own mind. 

e Forum: The “Exploring ES6” homepage links to a forum’ where you can discuss questions 
and ideas related to this book. 

e Errata (typos, errors, etc.): On the “Exploring ES6” homepage’, there are links to a form for 
submitting errata and to a list with submitted errata. 


Glossary and conventions 


+ Receiver (of a method call): Given a method call obj .m(- ++), obj is the receiver of the method 
call and accessible via this inside the method. 

e Signature of a function (or a method): The (type) signature of a function describes how the 
function is to be called, what its inputs and its output are. I’m using the syntax established by 
Microsoft TypeScript and Facebook Flow in this book. An example of a signature: 


parseInt(string : string, radix? : number) : number 


You can see that parseInt() expects a string and a number and returns a number. If the type 
of a parameter is clear, I often omit the type annotation. 


Documenting classes 
The API of a class C is usually documented as follows: 


e C constructor 
e Static C methods 
e C.prototype methods 


Capitalization 
In English, I capitalize JavaScript terms as follows: 


e The names of primitive entities are not capitalized: a boolean value, a number value, a symbol, 
a string. One reason why P'm doing this is because TypeScript and Flow distinguish: 
— The type String: its members are objects, instances of String. 
— The type string: its members are primitive values, strings. 
e The data structure Map is capitalized. Rationale: distinguish from the Array method map (). 
e The data structure Set is capitalized. Rationale: distinguish from the verb set. 
e Array and Promise are capitalized. Rationale: easy to confuse with English words. 
e Not capitalized (for now): object, generator, proxy. 


*http://exploringjs.com/#forum 
Shttp://exploringjs.com/#errata 
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Demo code on GitHub 


Several repositories on GitHub contain code shown in this book: 


e async-examples* 

e babel-on-node? 

e demo_promise® 

e generator-examples” 
e node-es6-demo® 

e promise-examples” 


e webpack-es6-demo”” 


Sidebars 


Sidebars are boxes of text marked with icons. They complement the normal content. 


O Tips for reading 


Gives you tips for reading (what content to skip etc.). 


Code on GitHub 
(ap) 


Tells you where you can download demo code shown in this book. 


o Information 


General information. 


O Question 


Asks and answers a question, in FAQ style. 


“https://github.com/rauschma/async-examples 
*https://github.com/rauschma/babel-on-node 
Shttps://github.com/rauschma/demo_promise 
"https://github.com/rauschma/generator-examples 
Shttps://github.com/rauschma/node-esó6-demo 
"https://github.com/rauschma/promise-examples 


“https://github.com/rauschma/webpack-es6-demo 
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A Warning 


Things you need to be careful about. 


EA External material 


Points to related material hosted somewhere on the web. 


# Related parts of the spec 
os 


Explains where in the ES6 spec you can find the feature that is currently being explained. 


Footnotes 


Occasionally, I refer to (publicly available) external material via footnotes. Two sources are marked 
with a prefix in square brackets: 


e [Spec] refers to content in the HTML version of the ES6 spec. 
e [Speaking JS] refers to content in the HTML version of “Speaking JavaScript”. 


Preface 


You are reading a book about ECMAScript 6 (ES6), a new version of JavaScript. It’s great that we can 
finally use that version, which had a long and eventful past: It was first conceived as ECMAScript 4, 
a successor to ECMAScript 3 (whose release was in December 1999). In July 2008, plans changed and 
the next versions of JavaScript were to be first a small incremental release (which became ES5) and 
then a larger, more powerful release. The latter had the code name Harmony and part of it became 
ES6. 


ECMAScript 5 was standardized in December 2009. I first heard and blogged** about ECMAScript 6 
in January 2011, when it was still called Harmony. The original plan was to finish ES6 in 2013, but 
things took longer and it was standardized in June 2015. (A more detailed account of ES6’s history 
is given in the next chapter.) 


With a few minor exceptions, I am happy how ECMAScript 6 turned out. This book describes my 
experiences with, and my research of, its features. Similarly to ES6, it took a long time to finish — 
in a way, I started writing it in early 2011. Like my previous book “Speaking JavaScript’””, I wrote 
most of it as a series of blog posts. I like the discussion and feedback that this open process enables, 
which is why this book is available for free online. 


The offline version (PDF, EPUB, MOBI) of Exploring ES6 is sold as a living book: You buy an early 
version and get free upgrades until it is completely done. It will take a while until that happens, but 
despite that, it is already a very complete book. 


I hope that reading the book conveys some of the fun I had investigating and playing with ESo. 
Axel 


“http://www.2ality.com/2011/01/brendan-eichs-dream-for-next-version- of.html 
“http://speakingjs.com/ 
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| Background 


1. About ECMAScript 6 (ES6) 


It took a long time to finish it, but ECMAScript 6, the next version of JavaScript, is finally a reality: 


+ It became a standard in June 2015. 

e Its features are slowly appearing in JavaScript engines (as documented in kangax’ ES6 
compatibility table’). 

e Transpilers (such as Babel? and Traceur?) let you compile ES6 to ES5. 


The next sections explain concepts that are important in the world of ES6. 


1.1 TC39 (Ecma Technical Committee 39) 


TC39 (Ecma Technical Committee 39)* is the committe that evolves JavaScript. Its members are 
companies (among others, all major browser vendors). TC39 meets regularly”, its meetings are 
attended by delegates that members send and by invited experts. Minutes of the meetings are 
available online? and give you a good idea of how TC39 works. 


1.2 How ECMAScript 6 was designed 


The ECMAScript 6 design process centers on proposals for features. Proposals are often triggered by 
suggestions from the developer community. To avoid design by committee, proposals are maintained 
by champions (1-2 committee delegates). 


A proposal goes through the following steps before it becomes a standard: 


e Sketch (informally: “strawman proposal”): A first description of the proposed feature. 

e Proposal: If TC39 agrees that a feature is important, it gets promoted to official proposal status. 
That does not guarantee it will become a standard, but it considerably increases its chances. 
The deadline for ES6 proposals was May 2011, no major new proposals were considered after 
that. 


*http://kangax.github.io/compat-table/es6/ 
?https://babeljs.io/ 
$https://github.com/google/traceur-compiler 
‘http://www.ecma-international.org/memento/TC39.htm 
*http://www.ecma-international.org/memento/TC39-M.htm 
Shttps://github.com/tc39/tc39-notes 
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e Implementations: Proposed features must be implemented, ideally in two JavaScript engines. 
Implementations and feedback from the community shape the proposal as it evolves. 

e Standard: If the proposal continues to prove itself and is accepted by TC39, it will eventually 
be included in an edition of the ECMAScript standard. At this point, it is a standard feature. 


[Source of this section: “The Harmony Process”” by David Herman. ] 


1.2.1 The design process after ES6 


Starting with ECMAScript 7 (whose official name is ECMAScript 2016), TC39 will time-box releases. 
The plan is to release a new version of ECMAScript every year, with whatever features are ready at 
that time. That means that from now on, ECMAScript versions will be relatively small upgrades. 


Work on ECMAScript 2016 (and later) has already begun, current proposals* are listed on GitHub. 
The process has changed, too and is described in a TC39 process document”. 


1.3 JavaScript versus ECMAScript 


JavaScript is what everyone calls the language, but that name is trademarked (by Oracle, which 
inherited the trademark from Sun). Therefore, the official name of JavaScript is ECMAScript. That 
name is comes from the standard organization Ecma, which manages the language standard. Since 
ECMAScript’s inception, the name of the organization changed from the acronym “ECMA” to the 
proper name “Ecma”. 


Versions of JavaScript are defined by specifications that carry the official name of the language. 
Hence, the first standard version of JavaScript is ECMAScript 1 which is short for “ECMAScript 
Language Specification, Edition 1”. ECMAScript x is often abbreviated ESx. 


1.4 Upgrading to ES6 
The stake holders on the web are: 
e Implementors of JavaScript engines 


e Developers of web applications 
e Users 


"http://tc39wiki.calculist.org/about/harmony/ 
Shttps://github.com/tc39/ecma262 
*lnttps://tc39.github.io/process-document/ 
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These groups have remarkably little control over each other. That’s why upgrading a web language 
is so challenging. 


On one hand, upgrading engines is challenging, because they are confronted with all kinds of code on 
the web, sometimes very old one. You also want engine upgrades to be automatic and unnoticeable 
for users. Therefore, ES6 is a superset of ES5, nothing is removed’’. ES6 upgrades the language 
without introducing versions or modes. It even manages to make strict mode the de-facto default 
(via modules), without increasing the rift between it and sloppy mode. The approach that was taken 
is called “One JavaScript” and explained in a separate chapter. 


On the other hand, upgrading code is challenging, because your code must run on all JavaScript 
engines that are used by your target audience. Therefore, if you want to use ES6 in your code, you 
only have two choices: You can either wait until no one in your target audience uses a non-ES6 
engine, anymore. That will take years; mainstream audiences were at that point w.r.t. ES5 when ES6 
became a standard in June 2015. And ES5 was standardized in December 2009! Or you can compile 
ES6 to ES5 and use it now (how that is done is explained in a separate chapter). 


Goals and requirements clash in the design of ES6: 


e Goals are fixing JavaScript’s pitfalls and adding new features. 
e Requirements are that both need to be done without breaking existing code and without 
changing the lightweight nature of the language. 


1.5 Goals for ES6 


The original project page for Harmony/ES6”' includes several goals. In the following subsections, 
Pm taking a look at some of them. 


1.5.1 Goal: Be a better language 


The goal is: Be a better language for writing: 


i. complex applications; 
ii. libraries (possibly including the DOM) shared by those applications; 
iii. code generators targeting the new edition. 


Sub-goal (i) acknowledges that applications written in JavaScript have grown huge. A key ES6 
feature fulfilling this goal is built-in modules. 


This is not completely true: there are a few minor breaking changes that don't affect code on the web. These are detailed in section D.1 and 
section E.1 of the ES6 specification. 


“http://wikiecmascript.org/doku.php?id=harmony:harmony 
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Modules are also an answer to goal (ii). As an aside, the DOM is notoriously difficult to implement 
in JavaScript. ES6 Proxies should help here (as described in a separate chapter). 


Several features were specifically added not to improve JavaScript, but to make it easier to compile 
to JavaScript. Two examples are: 


e Math. fround() — rounding Numbers to 32 bit floats 
e Math. imul() — multiplying two 32 bit ints 


They are both useful for, e.g., compiling C/C++ to JavaScript via Emscripten””. 


1.5.2 Goal: Improve interoperation 


The goal is: Improve interoperation, adopting de facto standards where possible. 


Three examples are: 


e Classes: are based on how constructor functions are currently used. 

e Modules: picked up design ideas from the CommonJS module format. 

e Arrow functions: have syntax that is borrowed from CoffeeScript. 

e Named function parameters: There is no built-in support for named parameters. Instead, the 
existing practice of naming parameters via object literals is supported via destructuring in 
parameter definitions. 


1.5.3 Goal: Versioning 


The goal is: Keep versioning as simple and linear as possible. 


As mentioned previously, ES6 avoids versioning via “One JavaScript”: In an ES6 code base, 
everything is ES6, there are no parts that are ES5-specific. 


1.6 An overview of ES6 features 


Quoting the introduction of the ECMAScript 6 specification: 


Some of [ECMAScript 6’s] major enhancements include modules, class declarations, 
lexical block scoping, iterators and generators, promises for asynchronous program- 
ming, destructuring patterns, and proper tail calls. The ECMAScript library of built-ins 
has been expanded to support additional data abstractions including maps, sets, and 
arrays of binary numeric values as well as additional support for Unicode supplemental 
characters in strings and regular expressions. The built-ins are now extensible via 
subclassing. 


“https://github.com/kripken/emscripten 
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There are three major groups of features: 


e Better syntax for features that already exist (e.g. via libraries). For example: 
— Classes 
— Modules 
e New functionality in the standard library. For example: 
— New methods for strings and Arrays 
— Promises 
— Maps, Sets 
e Completely new features. For example: 
— Generators 
— Proxies 
— WeakMaps 


1.7 A brief history of ECMAScript 
This section describes what happened on the road to ECMAScript 6. 


1.7.1 The early years: ECMAScript 1-3 


e ECMAScript 1 (June 1997) was the first version of the JavaScript language standard. 

e ECMAScript 2 (June 1998) contained minor changes, to keep the spec in sync with a separate 
ISO standard for JavaScript. 

e ECMAScript 3 (December 1999) introduced many features that have become popular parts 
of the language”: 


1.7.2 ECMAScript 4 (abandoned in July 2008) 


Work on ES4 started after the release of ES3 in 1999. In 2003, an interim report was released 
after which work on ES4 paused. Subsets of the language described in the interim report were 
implemented by Adobe (in ActionScript) and by Microsoft (in JScript.NET). 


In February 2005, Jesse James Garrett observed that new techniques had become popular for 
implementing dynamic frontend apps in JavaScript. He called those techniques Ajax**. Ajax enabled 
a completely new class of web apps and led to a surge of interest in JavaScript. 


That may have contributed to TC39 resuming work on ES4 in fall 2005. They based ES4 on ES3, the 
interim ES4 report and experiences with ActionScript and JScript.NET. 


There were now two groups working on future ECMAScript versions: 


Source: Introduction of ES6 spec. 


[...] regular expressions, better string handling, new control statements, try/catch exception handling, tighter definition of errors, 
formatting for numeric output and other enhancements. [1] 


“http://www.adaptivepath.com/ideas/ajax-new-approach-web-applications/ 
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e ECMAScript 4 was designed by Adobe, Mozilla, Opera, and Google and was a massive 
upgrade. Its planned feature sets included: 
— Programming in the large (classes, interfaces, namespaces, packages, program units, 
optional type annotations, and optional static type checking and verification) 
— Evolutionary programming and scripting (structural types, duck typing, type definitions, 
and multimethods) 
— Data structure construction (parameterized types, getters and setters, and meta-level 
methods) 
— Control abstractions (proper tail calls, iterators, and generators) 
— Introspection (type meta-objects and stack marks) 
e ECMAScript 3.1 was designed by Microsoft and Yahoo. It was planned as a subset of ES4 and 
an incremental upgrade of ECMAScript 3, with bug fixes and minor new features. ECMAScript 
3.1 eventually became ECMAScript 5. 


The two groups disagreed on the future of JavaScript and tensions between them continued to 
increase. 


EA Sources of this section: 


e “Proposed ECMAScript 4th Edition — Language Overview*””. 2007-10-23 
e “ECMAScript Harmony’ by John Resig. 2008-08-13 


1.7.3 ECMAScript Harmony 


At the end of July 2008, there was a TC39 meeting in Oslo, whose outcome was described” as follows 
by Brendan Eich: 


It's no secret that the JavaScript standards body, Ecma’s Technical Committee 39, has 
been split for over a year, with some members favoring ES4 [...] and others advocating 
ES3.1 [...]. Now, Pm happy to report, the split is over. 


The agreement that was worked out at the meeting consisted of four points: 


1. Develop an incremental update of ECMAScript (which became ECMAScript 5). 


Bhttp://www.ecmascript.org/es4/spec/overview.pdf 
*http://ejohn.org/blog/ecmascript-harmony/ 
https://mail.mozilla.org/pipermail/es-discuss/2008- August/006837.html 
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2. Develop a major new release, which was to be more modest than ECMAScript 4, but much 
larger in scope than the version after ECMAScript 3. This version was code-named Harmony, 
due to the nature of the meeting in which it was conceived. 

3. Features from ECMAScript 4 that would be dropped: packages, namespaces, early binding. 

4. Other ideas were to be developed in consensus with all of TC39. 


Thus: The ES4 group agreed to make Harmony less radical than ES4, the rest of TC39 agreed to keep 
moving things forward. 


The next versions of ECMAScript are: 


e ECMAScript 5 (December 2009). This is the version of ECMAScript that most browsers 
support today. It brings several enhancements to the standard library and updated language 
semantics via a strict mode. 

e ECMAScript 6 (June 2015). This version went through several name changes: 

- ECMAScript Harmony: was the initial code name for JavaScript improvements after 
ECMAScript 5. 

— ECMAScript.next: It became apparent that the plans for Harmony were too ambitious 
for a single version, so its features were split into two groups: The first group of features 
had highest priority and was to become the next version after ES5. The code name of 
that version was ECMAScript.next, to avoid prematurely comitting to a version number, 
which proved problematic with ES4. The second group of features had time until after 
ECMAScript.next. 

— ECMAScript 6: As ECMAScript.next matured, its code name was dropped and every- 
body started to call it ECMAScript 6. 

— ECMAScript 2015: In late 2014, TC39 decided to change the official name of ECMAScript 
6 to ECMAScript 2015, in light of upcoming yearly spec releases. However, given how 
established the the name “ECMAScript 6” already is and how late TC39 changed their 
minds, I expect that that’s how everybody will continue to refer to that version. 

e ECMAScript 2016 was previously called ECMAScript 7. Starting with ES2016, the language 
standard will see smaller yearly releases. 


2. FAQ: ECMAScript 6 


This chapter answers a few frequently asked questions about ECMAScript 6. 


2.1 Isn't ECMAScript 6 now called ECMAScript 2015? 


Yes and no. The official name is ECMAScript 2015, but ES6 is the name that everyone knows and 
uses. That's why I decided to use the latter for this book. 


After ES6, ECMAScript editions are created via a new process’ and a yearly release cycle. That 
seems like a good opportunity to switch to the new naming scheme. Therefore, I’ll use the name 
“ECMAScript 2016” for the edition after ES6. 


2.2 How much of ES6 is supported natively by current 
engines? 


The best way to check how much of ES6 various engines support is Kangax’ ES6 compatibility table’. 


2.3 How do | migrate my ECMAScript 5 code to 
ECMAScript 6? 


There is nothing to do: ECMAScript 6 is a superset of ECMAScript 5. Therefore, all of your ES5 code 
is automatically ES6 code. How exactly ES6 stays completely backwards compatible is explained in 
the chapter on “One JavaScript”. 


Consult the chapter “Deploying ECMAScript 6” if you are wondering how you can use new ES6 
features today (which is a different question). 


2.4 Does it still make sense to learn ECMAScript 5? 


As the chapter “Deploying ECMAScript 6” demonstrates, you can already exclusively program in 
ES6 today, without ever having to write code in an older JavaScript version. Does that mean that 
you shouldn't learn ECMAScript 5, anymore? It doesn't, for several reasons: 


"https://tc39.github.io/process- document/ 
*http://kangax.github.io/compat-table/es6/ 
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e ECMAScript 6 is a superset of ECMAScript 5 — new JavaScript versions must never break 
existing code. Thus, nothing you learn about ECMAScript 5 is learned in vain. 

e There are several ECMAScript 6 features that kind of replace ECMAScript 5 features, but still 
use them as their foundations. It is important to understand those foundations. Two examples: 
classes are internally translated to constructors and methods are still functions (as they have 
always been). 

e As long as ECMAScript 6 is compiled to ECMAScript 5, it is useful to understand the output 
of the compilation process. And you'll have to compile to ES5 for a while (probably years), 
until you can rely on ES6 being available in all relevant browsers. 

e It’s important to be able to understand legacy code. 


2.5 Is ES6 bloated? 


I’ve seen people complain about ES6 making JavaScript bloated and introducing too much useless 
“syntactic sugar” (more convenient syntax for something that already exists). 


If someone feels that way, I suggest that they use ES6 for a while. Nobody forces you to use any of 
the new features. You can start small (e.g. with template literals and arrow functions) and then use 
more new features, as you grow more comfortable with ES6. So far, the feedback I get from people 
who have actually used ES6 (as opposed to read about it) is overwhelmingly positive. 


Furthermore, things that superficially look like syntactic sugar (such as classes and modules) bring 
much-needed standardization to the language and serve as foundations for future features. 


Lastly, several features were not created for normal programmers, but for library authors (e.g. 
generators, iterators, proxies). “Normal programmers” only need to know them superficially if at 
all. 


2.6 Isn't the ES6 specification very big? 


The ECMAScript specification has indeed grown tremendously: The ECMAScript 5.1 PDF had 245 
pages, the ES6 PDF has 593 pages. But, for comparison, the Java 8 language specification has 724 
pages (excluding an index). Furthermore, the ES6 specification contains details that many other 
language specifications omit as implementation-defined. It also specifies how its standard library 
works’. 


2.7 Does ES6 have array comprehensions? 


Originally, ES6 was to have Array and Generator comprehensions (similarly to Haskell and Python). 
But they were postponed until after ES6, because TC39 wanted to explore two avenues: 


Source: Tweet by Allen Wirfs-Brock. https://twitter.com/awbjs/status/574649464687734785 
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e It may be possible to create comprehensions that work for arbitrary datatypes (think Mi- 
crosoft’s LINQ). 

e It may also be possible that methods for iterators are a better way to achieve what compre- 
hensions do. 


2.8 Is ES6 statically typed? 


Static typing is not part of ES6. However, the following two technologies add static typing to 
JavaScript. Similar features may eventually be standardized. 


e Microsoft TypeScript: is basically ES6 plus optional type annotations. At the moment, it is 
compiled to ES5 and throws away the type information while doing so. Optionally, it can 
also make that information available at runtime, for type introspection and for runtime type 
checks. 

e Facebook Flow: is a type checker for ECMAScript 6 that is based on flow analysis. As such, 
it only adds optional type annotations to the language and infers and checks types. It does not 
help with compiling ES6 to ES5. 


Three benefits of static typing are: 


+ It allows you to detect a certain category of errors earlier, because the code is analyzed stat- 
ically (during development, without running code). As such, static typing is complementary 
to testing and catches different errors. 

e It helps IDEs with auto-completion. 


Both TypeScript and Flow are using the same notation. Type annotations are optional, which 
makes this approach relatively lightweight. Even without annotations, types can often be inferred. 
Therefore, this kind of type checking is even useful for completely unannotated code, as a 
consistency check. 


2.9 Should I avoid classes? 


I recommend to use them. I explain their pros and cons in the chapter on classes. 


2.10 Does ES6 have traits or mixins? 


No, but one of the goals for classes was for them to be a foundation on which traits (or a similar 
way of doing multiple inheritance) can be built. 


The library traits.js* gives you a preview of what traits may look like. This being a library limits it 
syntactically; should traits ever become a language feature, they will have nicer syntax. 


*http://soft.vub.ac.be/-tvcutsem/traitsjs/ 
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2.11 Why are there “fat” arrow functions (=>) in ES6, 
but no “thin” arrow functions (->)? 


ECMAScript 6 has syntax for functions with a lexical this, so-called arrow functions. However, it 
does not have arrow syntax for functions with dynamic this. That omission was deliberate; method 
definitions cover most of the use cases for thin arrows. If you really need dynamic this, you can 
still use a traditional function expression. 


2.12 Where can I find more ES6 resources? 


These are two lists with ES6 resources: 


e “ECMAScript 6 Tools?” by Addy Osmani. 
e “ECMAScript 6 Learning!” by Eric Douglas. 


*https://github.com/addyosmani/es6-tools 
*https://github.com/ericdouglas/ES6-Learning 


3. One JavaScript: avoiding versioning 
in ECMAScript 6 


What is the best way to add new features to a language? This chapter describes the approach taken 
by ECMAScript 6. It is called One JavaScript, because it avoids versioning. 


3.1 Versioning 


In principle, a new version of a language is a chance to clean it up, by removing outdated features or 
by changing how features work. That means that new code doesn’t work in older implementations 
of the language and that old code doesn’t work in a new implementation. Each piece of code is linked 
to a specific version of the language. Two approaches are common for dealing with versions being 
different. 


First, you can take an “all or nothing” approach and demand that, if a code base wants to use the new 
version, it must be upgraded completely. Python took that approach when upgrading from Python 
2 to Python 3. A problem with it is that it may not be feasible to migrate all of an existing code base 
at once, especially if it is large. Furthermore, the approach is not an option for the web, where you'll 
always have old code and where JavaScript engines are updated automatically. 


Second, you can permit a code base to contain code in multiple versions, by tagging code with 
versions. On the web, you could tag ECMAScript 6 code via a dedicated Internet media type’. Such 
a media type can be associated with a file via an HTTP header: 


Content-Type: application/ecmascript;version=6 


It can also be associated via the type attribute of the <script> element (whose default value’ is 
text/javascript): 


<script type="application/ecmascript;version=6"> 


</script> 


This specifies the version out of band, externally to the actual content. Another option is to specify 
the version inside the content (in-band). For example, by starting a file with the following line: 


*http://en.wikipedia.org/wiki/Internet_media_type 
*http://www.w3.org/TR/html5/scripting- 1.html#attr-script-type 
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use version 6; 


Both ways of tagging are problematic: out-of-band versions are brittle and can get lost, in-band 
versions add clutter to code. 


A more fundamental issue is that allowing multiple versions per code base effectively forks a 
language into sub-languages that have to be maintained in parallel. This causes problems: 


e Engines become bloated, because they need to implement the semantics of all versions. The 
same applies to tools analyzing the language (e.g. style checkers such es JSLint). 

e Programmers need to remember how the versions differ. 

e Code becomes harder to refactor, because you need to take versions into consideration when 
you move pieces of code. 


Therefore, versioning is something to avoid, especially for JavaScript and the web. 


3.1.1 Evolution without versioning 


But how can we get rid of versioning? By always being backwards-compatible. That means we must 
give up some of our ambitions w.r.t. cleaning up JavaScript: We can’t introduce breaking changes. 
Being backwards-compatible means not removing features and not changing features. The slogan 
for this principle is: “don’t break the web”. 


We can, however, add new features and make existing features more powerful. 


As a consequence, no versions are needed for new engines, because they can still run all old code. 
David Herman calls this approach to avoiding versioning One JavaScript (1JS) [1], because it avoids 
splitting up JavaScript into different versions or modes. As we shall see later, 1JS even undoes some 
of a split that already exists, due to strict mode. 


One JavaScript does not mean that you have to completely give up on cleaning up the language. 
Instead of cleaning up existing features, you introduce new, clean, features. One example for that is 
let, which declares block-scoped variables and is an improved version of var. It does not, however, 
replace var, it exists alongside it, as the superior option. 


One day, it may even be possible to eliminate features that nobody uses, anymore. Some of the ES6 
features were designed by surveying JavaScript code on the web. Two examples are: 


e let-declarations are difficult to add to non-strict mode, because let is not a reserved word 
in that mode. The only variant of let that looks like valid ES5 code is: 


let[x] = arr; 


Research yielded that no code on the web uses a variable let in non-strict mode in this 
manner. That enabled TC39 to add let to non-strict mode. Details of how this was done 
are described later in this chapter. 
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e Function declarations do occasionally appear in non-strict blocks, which is why the ES6 
specification describes measures that web browsers can take to ensure that such code doesn’t 
break. Details are explained later. 


The next chapter describes the opposite of what we have just looked at: deploying ES6 code so that 
it runs both on engines that support ES6 and on engines that don’t. 


3.2 Strict mode and ECMAScript 6 


Strict mode? was introduced in ECMAScript 5 to clean up the language. It is switched on by putting 
the following line first in a file or in a function: 


‘use strict'; 
Strict mode introduces three kinds of breaking changes: 


e Syntactic changes: some previously legal syntax is forbidden in strict mode. For example: 
— The with statement is forbidden. It lets users add arbitrary objects to the chain of 
variable scopes, which slows down execution and makes it tricky to figure out what 
a variable refers to. 
— Deleting an unqualified identifier (a variable, not a property) is forbidden. 
- Functions can only be declared at the top level of a scope. 
— More identifiers are reserved*: implements interface let package private 
protected public static yield 
e More errors. For example: 
— Assigning to an undeclared variable causes a ReferenceError. In non-strict mode, a 
global variable is created in this case. 
— Changing read-only properties (such as the length of a string) causes a TypeError. In 
non-strict mode, it simply has no effect. 
e Different semantics: Some constructs behave differently in strict mode. For example: 
— arguments doesn’t track the current values of parameters, anymore. 
- this is undefined in non-method functions. In non-strict mode, it refers to the 
global object (window), which meant that global variables were created if you called 
a constructor without new. 


Strict mode is a good example of why versioning is tricky: Even though it enables a cleaner version 
of JavaScript, its adoption is still relatively low. The main reasons are that it breaks some existing 
code, can slow down execution and is a hassle to add to files (let alone interactive command lines). 
I love the idea of strict mode and don’t nearly use it often enough. 


$http://speakingjs.com/es5/ch07.html#strict_mode 
“http://ecma-international.org/ecma-262/5.1/#sec-7.6.1.2 
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3.2.1 Supporting sloppy (non-strict) mode 


One JavaScript means that we can’t give up on sloppy mode: it will continue to be around (e.g. 
in HTML attributes). Therefore, we can’t build ECMAScript 6 on top of strict mode, we must add 
its features to both strict mode and non-strict mode (a.k.a. sloppy mode). Otherwise, strict mode 
would be a different version of the language and we'd be back to versioning. Unfortunately, two 
ECMAScript 6 features are difficult to add to sloppy mode: let declarations and block-level function 
declarations. Let’s examine why that is and how to add them, anyway. 


3.2.2 Let declarations in sloppy mode 


let enables you to declare block-scoped variables. It is difficult to add to sloppy mode, because Let 
is only a reserved word in strict mode. That is, the following two statements are legal ES5 sloppy 
code: 


var let = []; 
let[x] = 'abc'; 


In strict ECMAScript 6, you get an exception in line 1, because you are using the reserved word let 
as a variable name. And the statement in line 2 is interpreted as a let variable declaration (that uses 
destructuring). 


In sloppy ECMAScript 6, the first line does not cause an exception, but the second line is still 
interpreted as a let declaration. This way of using the identifier let is so rare on the web that ES6 
can afford to make this interpretation. Other ways of writing let declarations can't be mistaken for 
sloppy ES5 syntax: 


let foo = 123; 
let {x,y} = computeCoordinates(); 


3.2.3 Block-level function declarations in sloppy mode 


ECMAScript 5 strict mode forbids function declarations in blocks. The specification allowed them 
in sloppy mode, but didn’t specify how they should behave. Hence, various implementations of 
JavaScript support them, but handle them differently. 


ECMAScript 6 wants a function declaration in a block to be local to that block. That is OK as an 
extension of ES5 strict mode, but breaks some sloppy code. Therefore, ES6 provides “web legacy 
compatibility semantics”” for browsers that lets function declarations in blocks exist at function 
scope. 


*http://www.ecma-international.org/ecma-262/6.0/#sec-block-level-function-declarations-web-legacy-compatibility-semantics 
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3.2.4 Other keywords 


The identifiers yield and static are only reserved in ES5 strict mode. ECMAScript 6 uses context- 
specific syntax rules to make them work in sloppy mode: 


e In sloppy mode, yield is only a reserved word inside a generator function. 
e static is currently only used inside class literals, which are implicitly strict (see below). 


3.2.5 Implicit strict mode 


The bodies of modules and classes are implicitly in strict mode in ECMAScript 6 — there is no need 
for the 'use strict' marker. Given that virtually all of our code will live in modules in the future, 
ECMAScript 6 effectively upgrades the whole language to strict mode. 


The bodies of other constructs (such as arrow functions and generator functions) could have been 
made implicitly strict, too. But given how small these constructs usually are, using them in sloppy 
mode would have resulted in code that is fragmented between the two modes. Classes and especially 
modules are large enough to make fragmentation less of an issue. 


3.2.6 Things that can’t be fixed 


The downside of One JavaScript is that you can’t fix existing quirks, especially the following two. 


First, typeof null should return the string 'null' and not 'object'. But fixing that would break 
existing code. On the other hand, adding new results for new kinds of operands is OK, because 
current JavaScript engines already occasionally return custom values for host objects. One example 
are ECMAScript 6’s symbols: 


> typeof Symbol.iterator 
"symbol' 


Second, the global object (window in browsers) shouldn't be in the scope chain of variables. But it 
is also much too late to change that now. At least, one won't be in global scope in modules and let 
never creates properties of the global object, not even when used in global scope. 


3.3 Conclusion 


One JavaScript means making ECMAScript 6 completely backwards compatible. It is great that that 
succeeded. Especially appreciated is that modules (and thus most of our code) are implicitly in strict 
mode. 


In the short term, adding ES6 constructs to both strict mode and sloppy mode is more work when 
it comes to writing the language specification and to implementing it in engines. In the long term, 
both the spec and engines profit from the language not being forked (less bloat etc.). Programmers 
profit immediately from One JavaScript, because it makes it easier to get started with ECMAScript 
6. 
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3.4 Further reading 


[1] The original 1JS proposal (warning: out of date): “ES6 doesn’t need opt-in®” by David Herman. 


*http://esdiscuss.org/topic/es6-doesn-t-need-opt-in 


4. First steps with ECMAScript 6 


This chapter helps you take your first steps with ECMAScript 6: 


e It explains how you can interactively try out ES6. 
e It lists ES6 features that are easy to adopt, along with how those features are coded in ES5. 


4.1 Trying out ECMAScript 6 


There are three simple ways to play with ES6: 


1. Web browser: use the online Babel REPL’, an interactive playground that compiles ES6 to 
ES5. There is nothing to install with this option. 

2. Command line: use babel-node, a version of the Node.js executable that understands ES6 
(and internally compiles it to ES5). It can be installed via npm. 

3. Various JavaScript engines: check the ES6 compatibility table by kangax’ to find out which 
ES6 features are supported natively where. 


More details on options 1 and 2 are given next. 


4.1.1 The Babel REPL 


The Babel REPL has four major sections: 


e The top left pane contains the ES6 source code. 

e The bottom left pane shows syntax errors discovered in the ES6 code. 

e The top right pane contains the ES5 code that the ES6 code is compiled to. 
e The bottom right pane shows output produced via console.log(). 


*http://babeljs.io/repl/ 
*https://kangax.github.io/compat-table/es6/ 
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000 < OÑO babeljs.io © úl] O >» 


as 


Y Experimental @ Loose mode @ High compliancy Y) Evaluate 


TT let arr = [1, 2, 31; 
2 let squares = arr.map(x => x * x); 
3 console. log(squares); 


"use strict"; 


1 
2 
3 var arr = [1, 2, 31; 

4~ var squares = arr.map(function (x) { 
5 return Xx * xX; 

Gi) +); 

7 


console. log(squares); 


[1,4,9] 


4.1.2 babel-node 
The babel-node executable can be installed via npm: 
$ npm install --global babel 


You can use it in the same way as you would the Node.js executable node. Like node, an interactive 
REPL is started like this: 


$ babel-node 

Once you are in that REPL, you can execute ES6 code: 
> let arr = [1, 2, 315 

> arr.map(x => x * x) 


[ 1, 4,9] 


Note that babel-node does not currently support multi-line input?. 
The Babel website has more information the Babel CLI tools‘. 


The remaining sections of this chapter describe ES6 features that are easy to adopt. 


$https://github.com/babel/babel/issues/1741 
“http://babeljs.io/docs/usage/cli/ 
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4.2 From var to let/const 


ES6 has two new ways to declare variables: 


e let is (roughly) a block-scoped version of var. 
e const is like let, but creates constants, variables whose values can't be changed. 


You can generally replace each var with a let or a const. But you shouldn’t do so blindly, because 
the different kind of scoping can change how code behaves. As an example, look at the following 
ES5 code: 


var x = 3; 
function func(randomize) { 
if (randomize) { 
var x = Math.random(); // (A) scope: whole function 
return x; 
} 
return x; // accesses the x from line A 
} 
func(false); // undefined 


That func() returns undefined may be surprising. You can see why if you rewrite the code so that 
it more closely reflects what is actually going on: 


var x = 3; 
function func(randomize) { 
var x; 
if (randomize) { 
x = Math.random() ; 
return x; 
} 
return x; 


} 
func(false); // undefined 


If you replace var with let in the initial version, you get different behavior: 
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let x = 3; 
function func(randomize) { 
if (randomize) { 
let x = Math.random() ; 
return x; 


} 


return x; 


} 
func(false); // 3 


Thus, blindly replacing var with let or const is risky. My advice is: 


e Only use let/const in new code. 
e Leave old code as is or refactor it carefully. 


More information: chapter “Variables and scoping”. 


4.3 From IIFEs to blocks 


In ES5, you had to use an IIFE if you wanted to keep a variable local: 


(function () { // open IIFE 
var tmp = +++; 


}()); // close IIFE 
console. log(tmp); // ReferenceError 


In ECMAScript 6, you can simply use a block and a let declaration: 


{ // open block 
let tmp = °°: 


y) // close block 


console. log(tmp); // ReferenceError 


More information: section “Avoid IIFEs in ES6”. 
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4.4 From concatenating strings to template literals 


With ES6, JavaScript finally gets literals for string interpolation and multi-line strings. 


4.4.1 String interpolation 


In ES5, you put values into strings by concatenating those values and string fragments: 


function printCoord(x, y) { 
console.log('('+x+", '+y+')'); 


} 
In ES6 you can use string interpolation via template literals: 


function printCoord(x, y) { 
console.log(`(${x}, ${y})`); 
} 


4.4.2 Multi-line strings 


Template literals also help with representing multi-line strings. 


For example, this is what you have to do to represent one in ES5: 


var HTML5_SKELETON = 
'<!doctype html>\n' + 
t<html>\n" + 
'<head>in' + 
! <meta charset="UTF-8">\n' + 
y <title></title>\n' + 
"</head>\n' + 
"<body>\n' + 
'</body>\n' + 
fAemL> yn"; 


If you escape the newlines via backslashes, things look a bit nicer (but you still have to explicitly 
add newlines): 
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var HTML5_SKELETON = '\ 

<!doctype html>\n\ 

<html>\n\ 

<head>\n\ 
<meta charset="UTF-8">\n\ 
<title></title>\n\ 

</head>\n\ 

<body>\n\ 

</body>\n\ 

</html>"; 


ES6 template literals can span multiple lines: 


const HTML5_SKELETON = ` 

<!doctype html> 

<html> 

<head> 
<meta charset="UTF-8"> 
<title></title> 

</head> 

<body> 

</body> 

</html>”; 


(The examples differ in how much whitespace is included, but that doesn't matter in this case.) 


More information: chapter “Template literals and tagged templates”. 


4.5 From function expressions to arrow functions 


In current ES5 code, you have to be careful with this whenever you are using function expressions. 
In the following example, I create the helper variable _this (line A) so that the this of UiCompo- 
nent can be accessed in line B. 
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function UiComponent { 
var _this = this; // (A) 
var button = document.getElementById('myButton') ; 
button.addEventListener('click', function () { 
console. log('CLICK'); 
_this.handleClick(); // (B) 
}); 
} 
UiComponent.prototype.handleClick = function () { 


}; 
In ES6, you can use arrow functions, which don’t shadow this (line A, lexical this): 


class UiComponent { 
constructor () { 
let button = document.getElementById('myButton'); 
button.addEventListener('click', () => { 
console. log('CLICK'); 
this.handleClick(); // (A) 
$; 
} 
handleClick() { 


} 


Arrow functions are especially handy for short callbacks that only return results of expressions. 


In ES5, such callbacks are relatively verbose: 


var arr = [1, 2, 3]; 
var squares = arr.map(function (x) { return x x x }); 


In ES6, arrow functions are much more concise: 


let arr = [1, 2, 3]; 
let squares = arr.map(x => x * x); 


When defining parameters, you can even omit parentheses if the parameters are just a single 
identifier. Thus: (x) => x x xandx => x * x are both allowed. 


More information: chapter “Arrow functions”. 
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4.6 Handling multiple return values 


Some functions or methods return multiple values via arrays or objects. In ES5, you always need to 
create intermediate variables if you want to access those values. In ES6, you can avoid intermediate 
variables via destructuring. 


4.6.1 Multiple return values vía arrays 


exec () returns captured groups via an Array-like object. In ES5, you need an intermediate variable 
(matchObj in the example below), even if you are only interested in the groups: 


var matchObj = 
/*(\d\d\d\d)-(\d\d)-(\d\d)$/ 
.exec('2999-12-31'); 

var year = matchObj[1]; 

var month = matchObj [2]; 

var day = matchObj [3]; 


In ES6, destructuring makes this code simpler: 


let [, year, month, day] = 
/*(\d\d\d\d)-(\d\d)-(\d\d) $/ 
.exec('2999-12-31'); 


The empty slot at the beginning of the Array pattern skips the Array element at index zero. 


4.6.2 Multiple return values via objects 
The method Object .getO0wnPropertyDescriptor () return a property descriptors, an object that 
holds multiple values in its properties. 


In ES5, even if you are only interested in the properties of an object, you still need an intermediate 
variable (propDesc in the example below): 
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var obj = { foo: 123 }; 

var propDesc = Object.getOwnPropertyDescriptor(obj, 'foo'); 
var writable = propDesc.writable; 

var configurable = propDesc.configurable; 

console. log(writable, configurable); // true true 

In ES6, you can use destructuring: 


let obj = { foo: 123 }; 


let {writable, configurable} = 
Object.getOwnPropertyDescriptor(obj, 'foo'); 


console. log(writable, configurable); // true true 
{writable, configurable} is an abbreviation for: 
{ writable: writable, configurable: configurable } 


More information: chapter “Destructuring”. 


4.7 From for to forEach() to for-of 


Prior to ES5, you iterated over Arrays as follows: 


var arr = ['a', 'b', 'c']; 

for (var i=0; i<arr.length; i++) { 
var elem = arr[i]; 
console. log(elem) ; 


In ES5, you have the option of using the Array method forEach(): 


arr.forEach(function (elem) { 
console. log(elem) ; 


H; 


A for loop has the advantage that you can break from it, forEach() has the advantage of 
conciseness. 


In ES6, the for-of loop combines both advantages: 
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let arr = ['a', "D"; rera 
for (let elem of arr) { 
console. log(elem) ; 


} 


If you want both index and value of each array element, for-of has got you covered, too, via the 
new Array method entries () and destructuring: 


for (let [index, elem] of arr.entries()) { 
console.log(index+'. '+elem); 


J 


More information: section “The for-of loop”. 


4.8 Handling parameter default values 
In ES5, you specify default values for parameters like this: 
function foo(x, y) { 


x =x || 9; 
y=y || 9; 


ES6 has nicer syntax: 
function foo(x=0, y=0) { 
} 


An added benefit is that in ES6, a parameter default value is only triggered by undefined, while it 
is triggered by any falsy value in the previous ES5 code. 


More information: section “Parameter default values”. 


4.9 Handling named parameters 


A common way of naming parameters in JavaScript is via object literals (the so-called options object 
pattern): 
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selectEntries({ start: 0, end: -1 }); 


Two advantages of this approach are: Code becomes more self-descriptive and it is easier to omit 
arbitrary parameters. 


In ES5, you can implement selectEntries() as follows: 


function selectEntries(options) { 


var start = options.start || 0; 
var end = options.end || -1; 
var step = options.step || 1; 


} 


In ES6, you can use destructuring in parameter definitions and the code becomes simpler: 
function selectEntries({ start=0, end=-1, step=1 }) { 

i pes 

4.9.1 Making the parameter optional 

To make the parameter options optional in ES5, you'd add line A to the code: 


function selectEntries(options) { 
options = options || {}; // (A) 


var start = options.start || 0; 
var end = options.end || -1; 
var step = options.step || 1; 


} 

In ES6 you can specify {} as a parameter default value: 

function selectEntries({ start=0, end=-1, step=1 } = {}) { 
} 


More information: section “Simulating named parameters”. 


4.10 From arguments to rest parameters 


In ES5, if you want a function (or method) to accept an arbitrary number of arguments, you must 
use the special variable arguments: 


First steps with ECMAScript 6 30 


function logAllArguments() { 
for (var i=0; i < arguments.length; i++) { 
console. log(arguments[i]) ; 


In ES6, you can declare a rest parameter (args in the example below) via the .. . operator: 


function logAllArguments(...args) { 
for (let arg of args) { 
console. log(arg) ; 


Rest parameters are even nicer if you are only interested in trailing parameters: 


function format(pattern, ...args) { 


Handling this case in ES5 is clumsy: 


function format() { 
var pattern = arguments[0]; 
var args = arguments.slice(1); 


Rest parameters make code easier to read: You can tell that a function has a variable number of 
parameters just by looking at its parameter definitions. 


More information: section “Rest parameters”. 


4.11 From apply () to the spread operator (...) 


In ES5, you turn arrays into parameters via apply (). ES6 has the spread operator for this purpose. 


4.11.1 Math.max() 


ES5 — apply (): 
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> Math.max.apply(null, [-1, 5, 11, 3]) 
11 


ES6 — spread operator: 


> Math.max(...[-1, 5, 11, 3]) 
11 


4.11.2 Array.prototype.push() 


ES5 — apply (): 


var arrl 


Las "p 
var arr2 C 


[ 
et, Tas 


arrl.push.apply(arrl, arr2); 
li arri as: now ta", "be. “e's *d"] 


ES6 — spread operator: 


let arr1 = ['a', 'b']; 
let arr2 = ['c', 'd']; 


arrl.push(...arr2); 
fc arri Ts now [La"., "bt, Terg td"] 


More information: section “The spread operator (.. .)”. 


4.12 From concat() to the spread operator (.. .) 


The spread operator can also turn the contents of its operand into array elements. That means that 
it becomes an alternative to the Array method concat(). 


ES5 — concat(): 
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var arrl1 = ['a', 'b'] 
var arr2 = ['c']; 
var arr3 = d', 'e']; 


console.log(arrl.concat(arr2, arr3)); 
// [ ay Ds leri Ae 5 ta! | 


ES6 — spread operator: 


let arr1 = ['a', 'b'] 

let arr2 = ['c']; 

let arr3 = ['d', 'e']; 

console. log([...arrl, ...arr2, ...arr3]); 


// [ ra"; Ds es "a"s la! ] 


More information: section “The spread operator (.. .)”. 


4.13 From constructors to classes 


ES6 classes are mostly just more convenient syntax for constructor functions. 


4.13.1 Base classes 


In ES5, you implement constructor functions directly: 


function Person(name) { 
this.name = name; 

} 

Person.prototype.describe = function () { 
return 'Person called '+this.name; 


}; 


In ES6, classes provide slightly more convenient syntax for constructor functions: 
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class Person { 
constructor(name) { 
this.name = name; 
} 
describe() { 
return 'Person called '+this.name; 


4.13.2 Derived classes 


Subclassing is complicated in ES5, especially referring to super-constructors and super-properties. 
This is the canonical way of creating a sub-constructor of Person, Employee: 


function Employee(name, title) { 
Person.call(this, name); // super (name) 
this.title = title; 
F 
Employee.prototype = Object.create(Person.prototype) ; 
Emp Loyee.prototype.constructor = Employee; 
Employee .prototype.describe = function () { 
return Person. prototype.describe.call(this) // super.describe() 
+ ' (' + this.title + ')'; 
$5 


ES6 has built-in support for subclassing, via the extends clause: 


class Employee extends Person { 
constructor (name, title) { 
super (name) ; 
this.title = title; 
} 
describe() { 
return super.describe() + ' (' + this.title + ')'; 


More information: chapter “Classes”. 
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4.14 From custom error constructors to subclasses of 
Error 


In ES5, it is impossible to subclass the built-in constructor for exceptions, Error (the chapter 
“Subclassing Built-ins”” in “Speaking JavaScript” explains why). The following code shows a work- 
around that gives the constructor MyError important features such as a stack trace: 


function MyError() 4 
// Use Error as a function 
var superInstance = Error.apply(null, arguments) ; 
copyOwnPropertiesFrom(this, superInstance) ; 


} 
MyError.prototype = Object.create(Error.prototype) ; 
MyError.prototype.constructor = MyError; 


In ES6, all built-in constructors can be subclassed, which is why the following code achieves what 
the ES5 code can only simulate: 


class MyError extends Error { 


} 


More information: section “Subclassing built-in constructors”. 


4.15 From function expressions in object literals to 
method definitions 


In JavaScript, methods are properties whose values are functions. 


In ES5 object literals, methods are created like other properties. The property values are provided 
via function expressions. 


*http://speakingjs.com/es5/ch28.html 
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var obj = { 
foo: function () { 


}s 
bar: function () { 
this.foo(); 
}, // trailing comma is legal in ES5 


ES6 has method definitions, special syntax for creating methods: 


let obj = ( 
foo() { 


this.foo(); 


More information: section “Method definitions”. 


4.16 From objects to Maps 
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Using the language construct object as a map from strings to arbitrary values (a data structure) has 
always been a makeshift solution in JavaScript. The safest way to do so is by creating an object 
whose prototype is null. Then you still have to ensure that no key is ever the string '__proto__', 


because that property key triggers special functionality in many JavaScript engines. 


The following ES5 code contains the function countWords that uses the object dict as a map: 


var dict = Object.create(null); 
function countWords(word) { 
var escapedWord = escapeKey (word) ; 
if (escapedWord in dict) { 
dict[escapedWord] ++; 
} else { 
dict[escapedWord] = 1; 


} 
function escapeKey(key) ( 
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if (key.index0f('__proto__') === 0) £ 
return key+'%'; 
} else { 


return key; 


In ES6, you can use the built-in data structure Map and don’t have to escape keys. As a downside, 
incrementing values inside Maps is less convenient. 


let map = new Map(); 

function countWords(word) { 
let count = map.get(word) || 0; 
map.set(word, count + 1); 


Another benefit of Maps is that you can use arbitrary values as keys, not just strings. 


More information: 


e Section “The dict Pattern: Objects Without Prototypes Are Better Maps” in “Speaking 
JavaScript” 
e Chapter “Maps and Sets” 


4.17 From CommonjS modules to ES6 modules 


Even in ES5, module systems based on either AMD syntax or CommonJS syntax have mostly 
replaced hand-written solutions such as the revealing module pattern”. 


ES6 has built-in support for modules. Alas, no JavaScript engine supports them natively, yet. But 
tools such as browserify, webpack or jspm let you use ES6 syntax to create modules, making the 
code you write future-proof. 


4.17.1 Multiple exports 


In CommonJS, you export multiple entities as follows: 


*http://speakingjs.com/es5/ch17.html#dict_pattern 
"http://christianheilmann.com/2007/08/22/again-with-the-module-pattern-reveal-something-to-the-world/ 
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/{------ lib. js ===2=== 
var sqrt = Math.sqrt; 
function square(x) { 
return x * xX; 
} 
function diag(x, y) { 
return sqrt(square(x) + square(y)); 


} 

module.exports = { 
sqrt: sqrt, 
square: square, 
diag: diag, 

$; 

(=== 2==3 mainl.js ------ 


var square = require('lib').square; 
var diag = require('lib').diag; 


console.log(square(11)); // 121 
console. log(diag(4, 3)); // 5 
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Alternatively, you can import the whole module as an object and access square and diag via it: 


| =====> main2.js ------ 

var lib = require('lib'); 
console.log(lib.square(11)); // 121 
console.log(lib.diag(4, 3)); // 5 


In ES6, multiple exports are called named exports and handled like this: 


//------ lib.js ------ 
export const sqrt = Math.sqrt; 
export function square(x) { 
return x * xX; 
} 
export function diag(x, y) { 
return sqrt(square(x) + square(y)); 


J====== mainl.js ------ 

import { square, diag } from 'lib'; 
console.log(square(11)); // 121 
console. log(diag(4, 3)); // 5 
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The syntax for importing modules as objects looks as follows (line A): 


J {=== main2.js ------ 

import * as lib from 'lib'; // (A) 
console. log(lib.square(11)); // 121 
console. log(lib.diag(4, 3)); // 5 


4.17.2 Single exports 


Node.js extends CommonJS and lets you export single values from modules, via module. exports: 


pp myFunc.js ------ 
module.exports = function () { =: }; 
{ {=== mainl.js ------ 


var myFunc = require('myFunc'); 
myFunc(); 


In ES6, the same thing is done via export default: 


===> 22 myFunc.js =-=-=-=-- 

export default function () { +++ } // no semicolon! 
pp ====== maini. js ====== 

import myFunc from 'myFunc'; 

myFunc(); 


More information: chapter “Modules”. 


4.18 What to do next 
Now that you got a first taste of ES6, what should you do next? I have two suggestions: 


e In this book, each major feature of ES6 has its own chapter, which starts with an overview. 
Browsing the chapters is therefore a good way of getting a more complete picture of ES6. 

e The next chapter, “Deploying ECMAScript 6”, describes the options you have for deploying 
ES6 in current JavaScript environments. 


5. Deploying ECMAScript 6 


This chapter describes the options you have for deploying ECMAScript 6 in current JavaScript 
environments. It is selective w.r.t. the amount of tools it covers. If you want a comprehensive list of 
tools, I suggest you look at Addy Osmani's “ECMAScript 6 Tools’. 


5.1 Using ECMAScript 6 today 


What options do you have for using ECMAScript 6 today? 


ECMAScript 6 features are continually appearing in engines. You can look up which ones are already 
supported where in Kangax’ “ECMAScript 6 compatibility table”. Pd expect first JavaScript engines 
to fully support ES6 in late 2015 or early 2016. It will take longer until all current engines do so. 


Especially if you take support for legacy engines into consideration, compiling ES6 to ES5 will be 
the only viable option for using ES6 for quite a while. Compiling from source code to source code 
is also called transpiling. You can transpile ES6 either before deployment (statically) or at runtime 
(dynamically). The next section explains how that works, later sections describe other ES6 tools and 
libraries. 


The nice thing about ES6 is that it is a superset of ES5, which means that all of your ES5 code bases 
are already valid ES6. This helps tremendously with adopting ES6-specific features, because you can 
do so incrementally. 


5.1.1 Using ECMAScript 6 natively 


As soon as the first engine fully supports ES6 and until all non-ES6 engines go away, a hybrid 
approach could be used for client-side apps: 


e The server has two versions of each file: the native ES6 version and its transpilation, an ES5 
version. 

e When the web app starts, feature detection is used to check whether ES6 is fully supported. If 
it is, the ES6 version of the app is used. Otherwise, the ES5 version is used. 


Detecting ECMAScript versions is difficult, because many engines support parts of versions before 
they support them completely. For example, this is how you’d check whether an engine supports 
ECMAScript 6’s for-of loop — but that may well be the only ES6 feature it supports: 


*https://github.com/addyosmani/es6-tools 
*http://kangax.github.io/compat-table/es6/ 
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function isForOfSupported() { 


try { 
eval("for (var e of ['a']) 47"); 
return true; 
} catch (e) { 
// Possibly: check if e instanceof SyntaxError 


} 


return false; 


Kyle Simpson’s library ES Feature Tests? lets you detect whether an engine supports ES6: 


var ReflectSupports = require("es-feature-tests"); 


ReflectSupports("all", function (results) { 
if (results.letConst && results.arrow) ( 
// Use ES6 natively 
} else { 
// Use transpiled ES6 


H; 


npm may eventually support two versions of the same module, which would enable you to deliver 
libraries as both ES5 and ES6 for Node.js, io.js and client-side module systems that are based on 
npm. 


5.2 Transpilation tools 


There are three essential choices that you have to make for transpilation: 


e A transpiler (for your code) 
e A package manager (to install existing libraries) 
e A module system (for the complete app) 


Note that the choices are not completely independent, not every module system works with every 
package manager etc. The next sections explain each of these choices in more detail. 


Shttps://github.com/getify/es-feature-tests 
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5.2.1 Choosing a transpiler 


A transpiler compiles your ES6 code to ES5. Popular choices are: 


e TypeScript*: Is basically ECMAScript 6 plus optional type annotations. 

e Traceur”: is an ES6 transpiler by Google, the first popular one. Pronounced French, /twa.soes/; 
an English approximation is “truh-SIR” (source*, listen to native French speakers pronounce 
this word’). 

e Babel*: is a newer ES6 transpiler that whose popularity has grown tremendously recently. 
Babel supports React’s JSX syntax in addition to ES6. Pronounced “babble”. 


You can transpile the code either: 


e Statically (before deployment) 
e Dynamically (at runtime) 


5.2.1.1 Static transpilation 


As a build step, TypeScript, Traceur and Babel let you produce ES5 code in the following module 
formats. You can either invoke them directly or use a build tool (grunt, gulp, broccoli, etc.). 


«e AMD 

«e Common]S 

e ES6 module loader API: The ES6 code is transpiled to ES5 code that uses this API via a polyfill’. 
This format is not supported by TypeScript. 


In browsers, such ES5 modules are loaded via one of the module systems described later. On Node.js, 
you can use the built-in module system (other options exist, e.g. webpack and the ES6 Module Loader 
Polyfill). 


5.2.1.2 Dynamic transpilation 


In browsers, you transpile dynamically via a library plus a custom <script type="...">. This 
option exists for Traceur*” and Babel'”. 


For Node.js, Babel has tools for on-the-fly compilation. These are described in another section. 


p://www.typescriptlang.org/ 
ps://github.com/google/traceur-compiler 
ps://github.com/google/traceur-compiler/issues/1875 
p://www.forvo.com/word/traceur/ 

ps://babeljs.io/ 
ps://github.com/ModuleLoader/es6-module-loader 
ps://github.com/google/traceur-compiler/wiki/Getting-Started 


O a o o Lo oe 


ps://babeljs.io/docs/usage/browser/ 
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5.2.2 Choosing a package manager 


You need a package manager for installing third-party libraries. These are three popular ones: 


e npm” (CommonJS modules): is a package manager that was originally created for Node.js, but 
has grown in popularity for client-side development thanks to module packaging and loading 
tools such as browserify and webpack. 

e Bower’? (CommonJS or AMD modules): is a package manager for client-side code. 

e jspm'*: is a package manager for SystemJS (see next bullet list). It can install modules from 
a variety of sources, including GitHub and npm. One key feature of jspm is that external 
modules can also be written in ES6 (and will be transpiled), not just your own modules. 


5.2.3 Choosing a module system 


Module systems bring support for modules to ES5 browsers (Node.js has a built-in module system). 
That way, you can build your app out of modules — your own and library modules. Popular module 
systems are: 


e RequireJS”: is a loader for AMD modules, which can be statically created via TypeScript, 
Traceur or Babel. Loader plugins (based on Traceur and Babel) enable it to load ES6 modules. 


Browserify**: packages CommonJS modules (including ones installed via npm) so that they 
can be loaded in browsers. Supports ES6 modules via transforms (plugins) based on Traceur 
and Babel. 

e webpack”’: a packager and loader for either CommonJS modules (including ones installed via 
npm) or AMD modules (including ones installed via Bower). Supports ES6 modules via custom 
loaders (plugins) based on Traceur and Babel. 

SystemJS**: A module system based on the ES6 Module Loader Polyfill that supports ES6 
modules and the ES5 module formats CommonJS, AMD and “ES6 module loader API”. 


5.3 Other useful ES6 tools and libraries 


e Test tools (such as Jasmine and mocha) can mostly be used as is, because they work with the 
transpiled code and don’t have to understand the original ES6 code. Babel’s documention” 
has information on how to use it with various test tools. 


12h 
Bh 
h 
15h, 
16), 
17), 
181, 
19), 


ps://www.npmjs.com/ 
p://bower.io/ 

p://jspm.io/ 

p://requirejs.org/ 
p://browserify.org/ 
p://webpack.github.io/ 
ps://github.com/systemjs/systemjs 
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ps://babeljs.io/docs/using- babel/#misc 
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e The following linters all support ES6, but to varying degrees: 
— JSLint” (focus: enforcing coding practices) 
— JSHint” (focus: enforcing coding practices) 
— ESLint”” (focus: letting people implement their own style rules) 
— JSCS” (focus: enforcing code style) 
e Shims/polyfills enable you to use much of the ECMAScript 6 standard library in ES5 code: 
- es6-shim”™* 
- Core.js” (used by Babel) 
e ES6 parsers: 
— Esprima?* 
= Acorn” 


5.4 ES6 REPLs 


There are many REPLs (command lines) out there for interactively playing with ES6. The obvious 
choices are the interactive online playgrounds of the following projects: 


e TypeScript Playground” 
e Babel REPL” 
e Traceur Transcoding Demo?” 


Additionally, Babel brings ES6 support to the Node.js REPL via its babel-node tool. 


5.5 Are there ES6 features that can't be transpiled to 
ES5? 
Some ECMAScript 6 features cannot be transpiled (compiled) to ES5. ES6 has three kinds of features: 


e Better syntax for existing features 
e New functionality in the standard library 
e Completely new features 


The next sections explain for each kind of feature how difficult it is to transpile to ES5. 


20), 
21), 
22), 
23), 
24), 


tp://www.jslint.com/ 
t 
t 
t 
t 
https://github.com/zloirock/core-js 
t 
t 
t 
t 
t 


p://jshint.com/ 

p://eslint.org/ 

p://jscs.info/ 
ps://github.com/paulmillr/es6-shim/ 
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p://esprima.org/ 
ps://github.com/marijnh/acorn 
p://www.typescriptlang.org/Playground 
ps://babeljs.io/repl/ 


p://google.github.io/traceur-compiler/demo/repl.html 
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5.5.1 Better syntax for existing features 
ES6 provides better syntax for features that are already available via libraries. Two examples: 


e Classes 
e Modules 


Both can be relatively easily compiled to ES5. For example, this is an ES6 class: 


class Point { 
constructor() { 
this.x = x; 
this.y = y; 
} 
toString() { 
return `(${this.x}, ${this.y})`; 


} 


In loose mode, Babel produces nicer ES5 code, at the cost of not being completely faithful to ES6 
semantics. This is the previous code, transpiled in loose mode: 


"use strict"; 


var _classCallCheck = function (instance, Constructor) { 
if (!(instance instanceof Constructor)) { 
throw new TypeError("Cannot call a class as a function"); 


}; 


var Point = (function () { 
function Point() { 
_classCallCheck(this, Point); 


this.x = x; 
this.y = y; 


Point.prototype.toString = function toString() { 
return "(" + this.x + ", "+ this.y + ")"; 


}; 


return Point; 


HOS 
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5.5.2 New functionality in the standard library 


ES6 has a more comprehensive standard library than ES5. Additions include: 


e New methods for strings, arrays 
e Promises 
e Maps, Sets 


These can be provided via a library. Much of that functionality (such as String.prototype.repeat()) 
is even useful for ES5. A later section lists a few such libraries. 


5.5.3 Completely new features 


Some ES6 features are completely new and unrelated to existing features. Such features can never 
be transpiled completely faithfully. But some of them have reasonable simulations, for example: 


e let and const: are transpiled to var plus renaming of identifiers to avoid name clashes 
where necessary. That produces fast code and should work well in practice, but you don't get 
the immutable bindings that const creates in native ES6. 

e Symbols: transpiled to objects with unique IDs. They can be used as property keys, because the 
bracket operator coerces them to strings. Additionally, some property-enumerating functions 
(such as Object. keys ()) have to be patched to ignore property keys coming from symbols. 

e Generators: are compiled to state machines, which is a complex transformation, but works 
remarkably well. For example, this generator function: 


functionx gen() { 
for(let 1=0; i < 3; i++) { 
yield i; 
} 
} 


is translated to the following ES5 code: 
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var marked0$0 = [gen].map(regeneratorRuntime.mark) ; 
function gen() ( 
var i; 
return regeneratorRuntime.wrap(function gen$(context$1$0) { 
while (1) switch (context$1$0.prev = context$1$0.next) { 
case 0: 
i = 0; 


case 1: 
if (!(i < 3)) { 
context$1$0.next = 7; 
break; 


context$1$0.next = 4; 
return i; 


case 4: 
i++; 
context$1$0.next 
break; 


II 
E 


case 7: 
case "end": 
return context$1$0.stop(); 
} 
}, markedo$0[0], this); 
} 


You can see the state machine in the code, the next state is stored in context$1$0.next. 


Check out Facebook’s regenerator library” for more information. 

e WeakMaps: map keys to values without pointing to the keys in a manner that prevents them 
from being garbage-collected. An ES5 simulation of a WeakMap is an object that contains a 
unique ID (a string such as 'weakmap_072c-4328-af75'), but is otherwise empty. Each of 
its key-value entries is managed by storing the value in the key, via a property whose name 
is the WeakMap ID. That is quite a hack: memory is wasted and keys must be mutable. But 
one important feature of native WeakMaps is preserved: keys can be garbage-collected. The 
simulation works because all of the WeakMap operations (get, set, has, delete) require a 
key. There is no way to clear them or to enumerate their entries, keys or values. 


Other features are impossible to transpile (in a straightforward and general manner): 


https://github.com/facebook/regenerator 
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e Proxies: intercepting proxy operations is only possible if you make all operations on objects 
interceptible. And that would cause a tremendous performance penality. 

e Subclassable built-in constructors (e.g. Error and Array) 

e Tail call optimization (see dedicated chapter): implementing tail call optimization universally 
in ES5 would require a radical transformation of the ES6 code (e.g. tramplining”). The 
resulting code would be quite slow. 


5.6 Example transpilation setups 
The following sections describe three example setups: 


e Client-side ES6 via webpack and Babel (browsers, webpack, static transpilation) 

e Dynamically transpiled ES6 on Node.js via Babel (Node.js, Babel, dynamic transpilation) 

e Statically transpiled ES6 on Node.js via Babel and gulp (Node.js, Babel, gulp, static transpila- 
tion) 


5.7 Example setup: Client-side ES6 via webpack and 
Babel 


webpack”* is a client-side module builder and module loader. This section shows you how to write 
ECMAScript 6 code with it. 


lap) The code shown here is on GitHub, in the project webpack-es6-demo”*. 


5.7.1 webpack features 


Notable webpack features include: 


e Supported module formats: AMD, CommonJS 
— Via loader (plug-in): ES6 

e Supported package managers: Bower, npm 

e Loaders for non-code: CSS, templates, ... 

e On-demand loading (chunked transfer) 

e Built-in development server 


http://raganwald.com/2013/03/28/trampolines-in-javascript.html 
http://webpack.github.io/ 
https://github.com/rauschma/webpack-es6-demo 
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5.7.2 Installing webpack 


Install webpack: 
npm install -g webpack 
Enable support for ECMAScript 6 (via Babel”): Pick one of the following three options. 


e Per project: nom install babel-loader --save-dev 
e In your home directory: cd $HOME ; npm install babel-loader 
e Globally: nom install -g babel-loader 


5.7.3 Using webpack and ES6 in a project 


The demo project has the following structure: 


webpack-es6-demo/ 
es6/ 
Point.js 
main.js 
index.html 
webpack.config.js 


The directory es6/ contains the ES6 code that webpack will transpile to ES5, index.html is the 
entry page of the web app and webpack.config.js is the configuration file for webpack. The 
content of the files is shown later. 


The following command continuously watches the JavaScript files in the directory es6/. Whenever 
one of them changes (or when the command is first executed), they are compiled to a single file 
bundle.js: 


webpack --watch 


O In real-world projects, you probably won't use webpack directly, but via build tools such 
as grunt and gulp. 


After executing the previous command, you can open index.html in a web browser (directly from 
the file system if you'd like). index. html loads bundle.js, which means that you get to see what 
main.js is doing: 


https://babeljs.io/ 
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<!doctype html> 
<html> 
<head> 
<meta charset="UTF-8"> 
<title>webpack ES6 demo</title> 
</head> 
<body> 
<script src="bundle.js"></script> 
</body> 
</html> 


5.7.3.1 webpack.config.js 


This is the configuration file for webpack: 


// This module helps us with the configuration data 
var path = require('path'); 


// Configuration data 
module.exports = 4 


entry: './es6/main.js', 
output: { 
path: __dirname, 
filename: 'bundle.js' 
}s 
module: { 
loaders: [ 
{ test: path.join(__dirname, 'es6'), 
loader: 'babel-loader' } 
] 
} 


}; 


The file is a module that exports an object with the configuration data. It uses the Node.js variable 
__dirname that contains the path of the parent directory of the currently executed module. The 
configuration data has the following properties: 


e entry: This is where the execution of JavaScript code starts. webpack starts compiling here 
and continues by compiling its dependencies (imported modules), then the dependencies of 
the dependencies, etc. 

e output: webpack bundles the entry file and everything it depends on into the output file 
bundle.js. I am using the Node.js variable __dirname to specify where bundle. js should 
be put (in the same directory as webpack.config.j3s). 


Deploying ECMAScript 6 


e module. loaders: Support for ES6 is enabled via a the module loader babel- loader. 
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— Property test specifies what files the loader should transpile. You can specify a single 


test or multiple tests: 
* Single test: match an absolute path via a regular expression or a string 
* Multiple tests: array of single tests (logical “and”) 


5.7.3.2 ECMAScript 6 code 


The following two ECMAScript 6 files were packaged into bundle. js. 


main.js: 


import Point from './Point.js'; 
var body = document.querySelector('body'); 
body.textContent = 'Good point: ' + new Point(1, 23); 


Point.js: 


class Point { 
constructor(x, y) { 
this.x = x; 
this.y = y; 
} 
toString() { 
return '('+this.x+','+this.y+')'; 


} 


export default Point; 


O The paths used to import modules follow Node.js conventions. 


5.7.3.3 Using npm packages 


You can install packages via npm and use them from your ES6 code, seamlessly. For example: First 


install lodash?*. 


**https://lodash.com/ 
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$ mkdir node_modules 
$ npm install lodash 


Then use it anywhere in your ES6 code: 


import { zip } from 'lodash'; 
console. log(zip(['1', '2'], ['a', 'b'])); 


5.8 Example setup: Dynamically transpiled ES6 on 
Node.js via Babel 


This section explains how to use the ES6 transpiler Babel” with Node.js. 


lap) You can download the code shown in this section’? on GitHub. 


Alternative: static transpilation 


The approach explained in this section is convenient for experiments and development. But 
it uses on-the-fly transpilation, which means that startup is slower and that Babel needs to 
be installed on the production system. If you want to avoid those costs, you can transpile 
statically, as described in the next section. For libraries, you normally don't have a choice 
and have to statically transpile them to ES5, because you should not force your clients to 
transpile dynamically. 


5.8.1 Running normal Node.js code via Babel 


The npm package babel brings Babel support to Node.js: 


$ npm install --global babel 


This package contains the shell script babel-node, which is a Babel-ified version of node. 


compiles everything from ES6 to ES5 that is run or required. 


5.8.1.1 Getting an ES6 REPL via babel-node 


For example, you can start a REPL via the following shell command: 


37https://babeljs.io/ 
38https://github.com/rauschma/babel-on-node 
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It 
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$ babel-node 
In the REPL, you can use ES6: 


> [1,2,3].map(x => x * x) 
[ 1, 4, 9 ] 


5.8.1.2 Running ES6 scripts via babel-node 


babel-node also lets you run Node.js scripts such as the following one. 


// point.js 
export class Point { 
constructor(x, y) { 
this.x = x; 


this.y = y; 
} 
} 
if (require.main === module) ( 
let pt = new Point(7,4); 
console.log( "My point: ${JSON.stringify(pt)}°); 
} 


The following shell command runs point. js: 


$ babel-node point.js 
My point: {"x":7,"y":4} 


5.8.1.3 More babel features 


The package babel has many more features, which are all documented” on the Babel website. For 
example, from within a normal Node module, you can install a “require hook”, which compiles all 
required modules via Babel (except, by default, modules in node_modules). 


5.8.2 Running Jasmine unit tests via Babel 


Another npm package, babel-jest*°, is a preprocessor for the Jasmine-based unit testing tool Jest*’. 


One way to install babel-jest is by mentioning it in the devDependencies of your package. json: 


>°https://babeljs.io/docs/using-babel/#node-js 
“°https://github.com/babel/babel-jest 
““http://facebook.github.io/jest/ 
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"devDependencies": { 
"babel-jest": "x", 
*"jest=cióin:; aM 

}s 

meeripes": { 
"test": "jest" 

}s 

"jest": { 
"scriptPreprocessor": "<rootDir>/node_modules/babel-jest", 
"testFileExtensions": ["js"], 
"moduleFileExtensions": ["js", "json"], 
"testDirectoryName": "spec" 


Afterwards, you only need to execute the following command inside the directory of package. json 
and both babel-jest and a command line interface (CLI) for Jest will be installed. 


npm install 


The configuration options for Jest are documented‘? on its website. I have used testDirectoryName 
to specify that the tests are inside the directory spec (the default is __tests__). Let's add the 
following test file to that directory: 


// spec/point.spec.js 
import '../auto_mock_off'; 
import { Point } from '../point'; 


describe('Point', () => { 
it('sets up instance properties correctly', () => { 
let p = new Point(1, 5); 
console. log(JSON.stringify(p)) ; 
expect(p.x).toBe(1); 
expect(p.y).toBe(5); 
$; 
$»; 


(Importing '../auto_mock_off' is a trick so that Jest doesn’t auto-mock.) 


Because we have specified scripts.test in package. json, we can run all tests inside spec/ via 
the following command: 


“http://facebook.github.io/jest/docs/api.html 
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npm test 


5.9 Example setup: Statically transpiled ES6 on Node.js 
via Babel and gulp 


This section explains how to use ES6 on Node.js by statically transpiling it to ES5 via Babel and gulp. 


The previous section showed how to dynamically transpile ES6 at runtime (also via Babel). That is 
more convenient and should work for many projects, but occasionally you may want a simpler and 
faster setup for your runtime environment. 


5.9.1 Installation 


lap) The demo project node-es6-demo* used in this section is available on GitHub. 


Installation consists of downloading the project and executing the following commands, which 
install all npm packages that the project depends on: 


$ cd node-es6-demo/ 
$ npm install 


The repo has the following structure: 


node-es6-demo/ 
es5/ 
es6/ 
myapp.js 
gulpfile.js 


5.9.2 Source maps 


Source maps help whenever a programming language is compiled to JavaScript. Compiling source 
code to source code is also called transpiling. Examples of transpilation are: 


e Minification (normal JavaScript to minified JavaScript) 
e CoffeeScript 


“Shttps://github.com/rauschma/node-esó-demo 
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e ECMAScript 6 (ES6 to ES5) 


A source map is a file that accompanies the transpilation output and maps the lines of the output 
to lines in the input files. This information can be used by error messages and debuggers to refer to 
lines in the original instead of the transpilation result. There are two ways to let tools know about a 
source map: Either the transpilation output refers to the source map file in the last line or it embeds 
that file’s contents in the last line. 


More information on source maps 


For more information on source maps consult the article “Introduction to JavaScript Source 
Maps**” by Ryan Seddon on HTML5 Rocks. 


5.9.3 The gulp file 


I am handling transpilation via the build tool gulp*. It is configured via a file gulpfile.js ina 
project’s directory. That file is a normal Node.js module that requires a module gulp and uses it to 
define build tasks (various operations performed on the project’s files). 


Our gulpfile.js looks as follows: 


// Various helper modules 

var gulp = require('gulp'); 

var sourcemaps = require('gulp-sourcemaps'); 
var babel = require('gulp-babel'); 


var path = require('path'); 


// I manage the paths of this project via an object 
var paths = { 
es6: ['es6/xx/x*x.js'], 
es5: 'es5', 
// Must be absolute or relative to source map 
sourceRoot: path.join(__dirname, 'es6'), 


}; 


// First task: transpile the ES6 code 
gulp.task('babel', function () { // (A) 
return gulp.src(paths.es6) 


“4http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/ 


“Shttp://gulpjs.com/ 
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.pipe(sourcemaps.init()) // (B) 
.pipe(babel()) 
.pipe(sourcemaps.write('.', // (©) 
{ sourceRoot: paths.sourceRoot })) 
.pipe(gulp.dest(paths.es5)); 
}); 


// Second task: watch files, transpile if one of them changes 
gulp.task('watch', function() { // (D) 

gulp.watch(paths.es6, ['babel']); 
}); 


// The default task is 'watch' 
gulp.task('default', ['watch']); // (E) 


In order to make gulp do something you invoke it like this: 
$ gulp «name_of_task» 


Our gulpfile defines two tasks, babel (line A) and watch (line D). If you call gulp without any 
arguments, the default task is triggered. In this file, the default task is watch (line E). 


Source maps are created due to the code in line B and line C. If you omit the path in line C, the 
source map is inlined in the output file (vs. stored in a separate file). 


Hopefully you now have a rough understanding of how the gulp file works. For open questions, 
consult the gulp documentation**. 


5.9.4 Transpilation 


The file es6/myapp. js contains the ES6 code of the Node.js application: 


import { install } from 'source-map-support'; 
install(); 


console. log([1,2,3].map(x => x * x)); 


throw new Error('Test!'); 


“Shttps://github.com/gulpjs/gulp/blob/master/docs/README.md 
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Alas, Node.js does not come with built-in support for source maps. But it can be enabled via a library, 
e.g. the npm package source-map-support*’. That library needs to be called at least once in an 
app. The first two lines in the previous code take care of that. They also demonstrate that you can 
use any npm-installed package via ES6 syntax. 


The following gulp invocation transpiles myapp.js. 
$ gulp babel 


Alternatively, you can use gulp or gulp watch to continuously watch the ES6 files and transpile 
them whenever they are changed. 


The results of the transpilation are in the directory es5/: 
es5/ 

myapp.js 

myapp.js.map 


You can see the ES5 version of es6/myapp . js and the source map file myapp . js .map. The contents 
of the former file are: 


"use strict”; 

var _install = require('source-map-support') ; 

_install.install() ; 

console. log([1, 2, 3].map(function (x) { 
return x * x; 


+3); 


throw new Error('Test!'); 
//# sourceMappingURL=myapp.js.map 


5.9.5 Running the transpiled code 
The transpiled code is a normal ES5 Node.js app and is run as usual: 
$ node es5/myapp.js 


It produces the following output. Note that, thanks to the source map, the stack trace reports that 
the exception is thrown in line 6. That is the correct line in the ES6 file. 


“https://github.com/evanw/node-source-map-support 
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[1, 4, 9 ] 


/tmp/node-es6-demo/es6/myapp.js:6 
throw new Error('Test!'); 


Error: 
at 
at 
at 
at 
at 
at 
at 
at 


A 


Test! 

Object.<anonymous> (/tmp/node-es6-demo/es6/myapp.js:6:7) 
Module._compile (module.js:456:26) 
Object.Module._extensions..js (module. js:474:10) 

Module. load (module.js:356:32) 

Function.Module._load (module.js:312:12) 
Function.Module.runMain (module.js:497:10) 

startup (node.js:119:16) 

node.js:906:3 
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6. New number and Math features 


This chapter describes the new number and Math features of ECMAScript 6. 


6.1 Overview 
You can now specify integers in binary and octal notation: 


> OxFF // ES5: hexadecimal 


255 

> 0b11 // ES6: binary 
3 

> 0010 // ES6: octal 
8 


The global object Number gained a few new properties. Among others: 


e Number . EPSILON for comparing floating point numbers with a tolerance for rounding errors. 
e A method and constants for determining whether a JavaScript integer is safe (within the 
signed 53 bit range in which there is no loss of precision). 


6.2 New integer literals 


ECMAScript 5 already has literals for hexadecimal integers: 


> 0x9 
9 

> OXA 
10 

> 0x10 
16 

> OXxFF 
255 


ECMAScript 6 brings two new kinds of integer literals: 
e Binary literals have the prefix Ob or OB: 
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> 0b11 
3 

> 0b100 
4 


e Octal literals have the prefix 0o or 00 (yes, that's a zero followed by the capital letter O; you'll 
be fine if you use the first variant): 


007 


> 
4 
> 0010 
8 


Remember that the method Number. prototype. toString(radix) can be used to convert Num- 
bers back: 


> (255).toString(16) 
‘ff! 

> (4).toString(2) 
'100' 

> (8).toString(8) 
110" 


6.2.1 Use case for octal literals: Unix-style file permissions 


In the Node.js file system module’, several functions have the parameter mode. Its value is used to 
specify file permissions, via an encoding that is a holdover from Unix: 


e Permissions are specified for three categories of users: 
— User: the owner of the file 
— Group: the members of the group associated with the file 
— All: everyone 
e Per category, the following permissions can be granted: 
— r (read): the users in the category are allowed to read the file 
— w (write): the users in the category are allowed to change the file 
— x (execute): the users in the category are allowed to run the file 


That means that permissions can be represented by 9 bits (3 categories with 3 permissions each): 


*https://nodejs.org/api/fs.html 
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User Group All 


Permissions 1r,w,X 5,W,X T,W,X 
Bit 8,7,6 5,4,3 2,1,0 


The permissions of a single category of users are stored in 3 bits: 


Bits Permissions Octal digit 


000  --—— 0 
001 --x 1 
010 -w- 2 
011 -WX 3 
100  r-- 4 
101 r-x 5 
110 rw- 6 
111 rwx 7 


That means that octal numbers are a compact representation of all permissions, you only need 3 
digits, one digit per category of users. Two examples: 


e 755 = 111,101,101: I can change, read and execute; everyone else can only read and execute. 
e 640 = 110,100,000: I can read and write; group members can read; everyone can’t access at all. 


6.2.2 parseInt() and the new integer literals 


parseInt() has the following signature: 
parseInt(string, radix?) 


It provides special support for the hexadecimal literal notation — the prefix Ox (or 0X) of string is 
removed if: 


e radix is missing or 0. Then radix is set to 16. 
e radix is already 16. 


For example: 
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> parseInt('OxFF') 

255 

> parseInt('OxFF', 0) 
255 

> parseInt('OxFF', 16) 
255 


In all other cases, digits are only parsed until the first non-digit: 


parseInt('OxFF', 10) 


parseInt('OxFF', 17) 


Ov oO yv 


However, parseInt() does not have special support for binary or octal literals! 


parseInt('0b111') 
parseInt('0b111', 2) 


parseInt('111', 2) 


NI VO vVoO v 


parseInt('0010') 
parseInt('0010', 8) 


parseInt('10', 8) 


0 VOvo Vv 


If you want to parse these kinds of literals, you need to use Number (): 


> Number ('0b111') 
7 

> Number ('0010') 
8 


Alternatively, you can also remove the prefix and use parseInt() with the appropriate radix: 
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parseInt('111', 2) 


parseInt('10', 8) 


O vN vyv 


6.3 New static Number properties 


This section describes new properties that the constructor Number has picked up in ECMAScript 6. 


6.3.1 Previously global functions 


Four number-related functions are already available as global functions and have been added to 
Number, as methods: isFinite and isNaN, parseFloat and parseInt. All of them work almost 
the same as their global counterparts, but isFinite and isNaN don’t coerce their arguments to 
numbers, anymore, which is especially important for isNaN. The following subsections explain all 
the details. 


6.3.1.1 Number. isFinite (number ) 


Is number an actual number (neither Infinity nor -Infinity nor NaN)? 


> Number.isFinite(Infinity) 
false 

> Number.isFinite(-Infinity) 
false 

> Number.isFinite(NaN) 

false 

> Number.isFinite(123) 

true 


The advantage of this method is that it does not coerce its parameter to number (whereas the global 
function does): 


> Number.isFinite('123') 
false 

> isFinite('123') 

true 


6.3.1.2 Number. isNaN (number) 


Is number the value NaN? Making this check via === is hacky. NaN is the only value that is not equal 
to itself: 
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> let x = NaN; 
> x === NaN 
false 


Therefore, this expression is used to check for it 


Using Number .isNaN() is more self-descriptive: 


> Number. isNaN(x) 
true 


Number.isNaN() also has the advantage of not coercing its parameter to number (whereas the 
global function does): 


> Number.isNaN('???') 
false 

> isNaN('???') 

true 


6.3.1.3 Number. parseFloat and Number. parseInt 


The following two methods work exactly like the global functions with the same names. They were 
added to Number for completeness sake; now all number-related functions are available there. 


+ Number .parseFloat(string)? 
e Number .parseInt(string, radix)’ 


6.3.2 Number.EPSILON 


Especially with decimal fractions, rounding errors can become a problem in JavaScript*. For example, 
0.1 and 0.2 can be represented precisely, which you notice if you add them and compare them to 0.3 
(which can't be represented precisely, either). 


?[Speaking JS] parseFloat () in (“Speaking JavaScript”). 
[Speaking JS] parseInt () in (“Speaking JavaScript”). 
“[Speaking JS] The details of rounding errors are explained in “Speaking JavaScript”. 
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Number . EPSILON specifies a reasonable margin of error when comparing floating point numbers. It 
provides a better way to compare floating point values, as demonstrated by the following function. 


function epsEqu(x, y) { 
return Math.abs(x - y) < Number.EPSILON; 


} 
console. log(epsEqu(0.1+0.2, 0.3)); // true 


6.3.3 Number. isInteger (number) 


JavaScript has only floating point numbers (doubles). Accordingly, integers are simply floating point 
numbers without a decimal fraction. 


Number .isInteger (number) returns true if number is a number and does not have a decimal 
fraction. 


> Number .isInteger (-17) 
true 

> Number .isInteger (33) 
true 

> Number .isInteger (33.1) 
false 

> Number.isInteger ('33') 
false 

> Number .isInteger (NaN) 
false 

> Number.isInteger (Infinity) 
false 


6.3.4 Safe Integers 


JavaScript numbers have only enough storage space to represent 53 bit signed integers. That is, 
integers i in the range -2” < i < 2% are safe. What exactly that means is explained momentarily. The 
following properties help determine whether a JavaScript integer is safe: 


e Number .isSafeInteger (number) 
e Number .MIN_SAFE_INTEGER 
e Number .MAX_SAFE_INTEGER 
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The notion of safe integers centers on how mathematical integers are represented in JavaScript. In 
the range (-2%, 2%) (excluding the lower and upper bounds), JavaScript integers are safe: there is a 
one-to-one mapping between them and the mathematical integers they represent. 


Beyond this range, JavaScript integers are unsafe: two or more mathematical integers are represented 
as the same JavaScript integer. For example, starting at 2%, JavaScript can represent only every 
second mathematical integer: 


> Math.pow(2, 53) 
9007199254740992 


> 9007199254740992 
9007199254740992 
> 9007199254740993 
9007199254740992 
> 9007199254740994 
9007199254740994 
> 9007199254740995 
9007199254740996 
> 9007199254740996 
9007199254740996 
> 9007199254740997 
9007199254740996 


Therefore, a safe JavaScript integer is one that unambiguously represents a single mathematical 
integer. 


6.3.4.1 Static Number properties related to safe integers 


The two static Number properties specifying the lower and upper bound of safe integers could be 
defined as follows: 


Number .MAX_SAFE_INTEGER = Math.pow(2, 53)-1; 
Number .MIN_SAFE_INTEGER = -Number .MAX_SAFE_INTEGER; 


Number .isSafeInteger () determines whether a JavaScript number is a safe integer and could be 
defined as follows: 
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Number. isSafelnteger = function (n) { 
return (typeof n === 'number' && 
Math.round(n) === n && 
Number.MIN_SAFE_INTEGER <= n && 
n <= Number.MAX_SAFE_INTEGER) ; 


For a given value n, this function first checks whether n is a number and an integer. If both checks 
succeed, n is safe if it is greater than or equal to MIN_SAFE_INTEGER and less than or equal to 
MAX_SAFE_INTEGER. 


6.3.4.2 When are computations with integers correct? 


How can we make sure that results of computations with integers are correct? For example, the 
following result is clearly not correct: 


> 9007199254740990 + 3 
9007199254740992 


We have two safe operands, but an unsafe result: 


> Number .isSafeInteger (9007199254740990) 
true 

> Number .isSafeInteger (3) 

true 

> Number .isSafeInteger (9007199254740992) 
false 


The following result is also incorrect: 


> 9007199254740995 - 10 
9007199254740986 


This time, the result is safe, but one of the operands isn’t: 
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> Number .isSafeInteger (9007199254740995) 
false 

> Number.isSafeInteger (10) 

true 

> Number .isSafeInteger (9007199254740986) 
true 


Therefore, the result of applying an integer operator op is guaranteed to be correct only if all 
operands and the result are safe. More formally: 


isSafeInteger(a) && isSafeInteger(b) && isSafeInteger(a op b) 
implies that a op b is a correct result. 


o Source of this section 


“Clarify integer and safe integer resolution”, email by Mark S. Miller to the es-discuss 
mailing list. 


6.4 Math 


The global object Math has several new methods in ECMAScript 6. 


6.4.1 Various numerical functionality 


6.4.1.1 Math.sign(x) 


Returns the sign of x as -1 or +1. Unless x is either NaN or zero; then x is returned’. 


*https://mail.mozilla.org/pipermail/es- discuss/2013- August/032991.html 
“Internally, JavaScript has two zeros. Math. sign(-0) produces the result -0 and Math. sign(+0) produces the result +0. 
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> Math.sign(-8) 
-1 
> Math.sign(3) 


> Math.sign(0) 


> Math.sign(NaN) 


> Math.sign(-Infinity) 


> Math.sign(Infinity) 


6.4.1.2 Math. trunc (x) 


Removes the decimal fraction of x. Complements the other rounding methods Math. floor (), 
Math.ceil() and Math. round(). 


> Math.trunc(3.1) 
3 
> Math.trunc(3.9) 
3 
> Math.trunc(-3.1) 
-3 
> Math.trunc(-3.9) 
=3 


You could implement Math .trunc() like this: 


function trunc(x) { 
return Math.sign(x) * Math.floor(Math.abs(x)); 


6.4.1.3 Math.cbrt(x) 


Returns the cube root of x (Vx). 
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> Math.cbrt(8) 
2 


6.4.2 Using 0 instead of 1 with exponentiation and logarithm 


A small fraction can be represented more precisely if it comes after zero. I'll demonstrate this with 
decimal fractions (JavaScript’s numbers are internally stored with base 2, but the same reasoning 
applies). 

Floating point numbers with base 10 are internally represented as mantissa x 10°P°"""". The mantissa 
has a single digit before the decimal dot and the exponent “moves” the dot as necessary. That means 
if you convert a small fraction to the internal representation, a zero before the dot leads to a smaller 
mantissa than a one before the dot. For example: 


e (A) 0.000000234 = 2.34 x 10°’. Significant digits: 234 
+ (B) 1.000000234 = 1.000000234 x 10°. Significant digits: 1000000234 


Precision-wise, the important quantity here is the capacity of the mantissa, as measured in significant 
digits. That’s why (A) gives you higher precision than (B). 


You can see this in the following interaction: The first number (1 x 107*%) registers as different from 
zero, while the same number added to 1 registers as 1. 


6.4.2.1 Math. expm1(x) 


Returns Math. exp(x)-1. The inverse of Math. log1p(). 


Therefore, this method provides higher precision whenever Math. exp() has results close to 1. You 
can see the difference between the two in the following interaction: 


> Math.expm1(le-10) 
1.00000000005e-10 

> Math.exp(le-10)-1 
1.000000082740371e-10 


The former is the better result, which you can verify by using a library (such as decimal.js’) for 
floating point numbers with arbitrary precision (“bigfloats”): 


"https://github.com/MikeMcl/decimal.js/ 
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> var Decimal = require('decimal.js').config({precision:50}); 
> new Decimal(1e-10).exp() .minus(1).toString() 
'1.000000000050000000001666666666708333333e-10' 


6.4.2.2 Math. log1p(x) 


Returns Math.log(1 + x). The inverse of Math.expm1(). 
Therefore, this method lets you specify parameters that are close to 1 with a higher precision. 


We have already established that 1 + 1e-16 === 1. Therefore, it is no surprise that the following 
two calls of log() produce the same result: 


> Math.log(1 + le-16) 
0 

> Math.log(1 + 0) 

0 


In contrast, log1p() produces different results: 


> Math. Logip(le-16) 


le-16 
> Math.log1p(0) 
0 


6.4.3 Logarithms to base 2 and 10 


6.4.3.1 Math.log2(x) 


Computes the logarithm to base 2. 


> Math.log2(8) 
3 


6.4.3.2 Math.log10(x) 


Computes the logarithm to base 10. 


> Math.log10(100) 
2 
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6.4.4 Support for compiling to JavaScript 


Emscripten? pioneered a coding style that was later picked up by asm.js’: The operations of a virtual 
machine (think bytecode) are expressed in static subset of JavaScript. That subset can be executed 
efficiently by JavaScript engines: If it is the result of a compilation from C++, it runs at about 70% 
of native speed. 


The following Math methods were mainly added to support asm.js and similar compilation 
strategies, they are not that useful for other applications. 


6.4.4.1 Math. fround(x) 


Rounds x to a 32 bit floating point value (float). Used by asm.js to tell an engine to internally use 
a float value. 


6.4.4.2 Math. imul (x, y) 


Multiplies the two 32 bit integers x and y and returns the lower 32 bits of the result. This is the only 
32 bit basic math operation that can't be simulated by using a JavaScript operator and coercing the 
result back to 32 bits. For example, ¡div could be implemented as follows: 


function idiv(x, y) { 
return (x / y) | 0; 
} 


In contrast, multiplying two large 32 bit integers may produce a double that is so large that lower 
bits are lost. 


6.4.5 Bitwise operations 


e Math.clz32(x) 
Counts the leading zero bits in the 32 bit integer x. 


Shttps://github.com/kripken/emscripten 
?http://asmjs.org/ 
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> Math.clz32(0b01000000000000000000000000000000) 
1 
> Math.clz32(0b00100000000000000000000000000000) 
2 
> 


Math.clz32(2) 
30 
> Math.clz32(1) 
31 


0» 


Why is this interesting? Quoting “Fast, Deterministic, and Portable Counting Leading Zeros’” by 


Miro Samek: 


Counting leading zeros in an integer number is a critical operation in many DSP 
algorithms, such as normalization of samples in sound or video processing, as well as 
in real-time schedulers to quickly find the highest-priority task ready-to-run. 


6.4.6 Trigonometric methods 


e Math.sinh(x) 
Computes the hyperbolic sine of x. 
e Math.cosh(x) 
Computes the hyperbolic cosine of x. 
e Math.tanh(x) 
Computes the hyperbolic tangent of x. 
e Math.asinh(x) 
Computes the inverse hyperbolic sine of x. 
e Math.acosh(x) 
Computes the inverse hyperbolic cosine of x. 
e Math.atanh(x) 
Computes the inverse hyperbolic tangent of x. 
e Math.hypot(...values) 
Computes the square root of the sum of the squares of its arguments. 


6.5 FAQ: numbers 


6.5.1 How can I use integers beyond JavaScript's 53 bit range? 


JavaScript's integers have a range of 53 bits. That is a problem whenever 64 bit integers are needed. 
For example: In its JSON API, Twitter had to switch from integers to strings when tweet IDs became 
too large. 


“http://embeddedgurus.com/state-space/2014/09/fast-deterministic-and-portable-counting-leading-zeros/ 
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At the moment, the only way around that limitation is to use a library for higher-precision numbers 
(bigints or bigfloats). One such library is decimal.js””. 


Plans to support larger integers in JavaScript exist, but may take a while to come to fruition. 


™“https://github.com/MikeMcl/decimal.js/ 


7. New string features 


This chapter covers new features of strings in ECMAScript 6. 


7.1 Overview 
New string methods: 


> 'hello'.startsWith('hell') 


true 
> 'hello'.endswith('ello') 
true 
> 'hello'.includes('ell') 
true 


> 'doo '.repeat(3) 
'doo doo doo ' 


ES6 has a new kind of string literal, the template literal: 


// String interpolation via template literals (in backticks) 
let first = 'Jane'; 
let last = 'Doe'; 
console.log('Hello ${first} ${last}!°); 
// Hello Jane Doe! 


// Template literals also let you create strings with multiple lines 
let multiLine = ` 

This is 

a string 

with multiple 

lines’; 


7.2 Unicode code point escapes 


In ECMAScript 6, there is a new kind of Unicode escape that lets you specify any code point (even 
those beyond 16 bits): 
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console. log('\u{1F680}'); // ES6: single code point 
console. log('\uD83D\uDE80'); // ES5: two code units 


More information on escapes is given in the chapter on Unicode. 


7.3 String interpolation, multi-line string literals and 
raw String literals 


Template literals are described in depth in their own chapter. They provide three interesting features. 


First, template literals support string interpolation: 


let first = 'Jane'; 

let last = 'Doe'; 

console. log(* Hello ${first} ${last}!°); 
// Hello Jane Doe! 


Second, template literals can contain multiple lines: 
let multiline = ` 

This is 

a string 


with multiple 
lines’; 


Third, template literals are “raw” if you prefix them with the tag String. raw — the backslash is not 
a special character and escapes such as \n are not interpreted: 


let raw = String.raw Not a newline: An'; 
console. log(raw === 'Not a newline: \\n')3 // true 


7.4 Iterating over strings 


Strings are iterable, which means that you can use for-of to iterate over their characters: 
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for (let ch of 'abc') { 
console.log(ch); 


} 
// Output: 


// a 
// b 
// E 


And you can use the spread operator (. . .) to turn strings into Arrays: 


let chars = [...'abc']; 
Da”, *b*, 'e'] 


7.4.1 Iteration honors Unicode code points 


The string iterator splits strings along code point boundaries, which means that the strings it returns 
comprise one or two JavaScript characters: 


for (let ch of 'x\uD83D\uDE80y') 4 
console. log(ch. length) ; 


J 
// Output: 


// 1 
[4 2 
fi A 


7.4.2 Counting code points 


Iteration gives you a quick way to count the Unicode code points in a string: 


> [...'x\uD83D\uDE80y'].length 
3 


7.4.3 Reversing strings with non-BMP code points 


Iteration also helps with reversing strings that contain non-BMP code points (which are larger than 
16 bit and encoded as two JavaScript characters): 
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let str = 'x\uD83D\uDE80y'; 


// ES5: \uD83D\uDE80 are (incorrectly) reversed 
console. Log(str.split(’").reverse().join("")); 
// ‘'y\uDE80\uD83Dx' 


// ES6: order of \uD83D\uDE80 is preserved 
console. log([...str].reverse().join('')); 
// "yNuD83D1UDE80x' 


'*y1uDE801uD83Dx*' 
my PE DE ss 

Y 20 30) X 
*y\uD83D\uDE8@x' 


yg" 


The two reversed strings in the Firefox console. 


A Remaining problem: combining marks 


A combining mark is a sequence of two Unicode code points that is displayed as single 
symbol. The ES6 approach to reversing a string that I have presented here works for non- 
BMP code points, but not for combining marks. For those, you need a library, e.g. Mathias 
Bynens’ Esrever”. 


7.5 Numeric values of code points 


The new method codePointAt() returns the numeric value of a code point at a given index in a 
string: 


let str = 'x\uD83D\uDE80y'; 

console. log(str.codePointAt(0).toString(16)); // 78 
console. log(str.codePointAt(1).toString(16)); // 1f680 
console. log(str.codePointAt(3).toString(16)); // 79 


This method works well when combined with iteration over strings: 


*https://github.com/mathiasbynens/esrever 
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for (let ch of 'x\uD83D\uDE80y') { 
console.log(ch.codePointAt(0).toString(16)); 


} 
// Output: 


// 78 
// 1f680 


// 79 
The opposite of codePointAt() is String. fromCodePoint(): 


> String.fromCodePoint(0x78, Ox1f680, 0x79) === 'x\uD83D\uDE80y' 
true 


7.6 Checking for containment and repeating strings 
Three new methods check whether a string exists within another string; 


> 'hello'.startsWith('hell') 


true 
> 'hello'.endswith('ello') 
true 
> 'hello'.includes('ell') 
true 


Each of these methods has a position as an optional second parameter, which specifies where the 
string to be searched starts or ends: 


> 'hello'.startsWith('ello', 1) 
true 

> 'hello'.endswith('hell', 4) 
true 


> 'hello'.includes('ell', 1) 
true 
> 'hello'.includes('ell', 2) 
false 


The repeat () method repeats strings: 
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> 'doo '.repeat(3) 
'doo doo doo ' 


7.7 All new string methods 


Tagged templates: 


e String.raw(callSite, ...substitutions) : string 
Template tag for “raw” content (backslashes are not interpreted). 


Unicode and code points: 


e String.fromCodePoint(...codePoints : number[]) : string 
Turns numbers denoting Unicode code points into a string. 

e String.prototype.codePointAt(pos) : number 
Returns the number of the code point starting at position pos (comprising one or two 
JavaScript characters). 

e String.prototype.normalize(form? : string) : string 
Different combinations of code points may look the same. Unicode normalization’ changes 
them all to the same value(s), their so-called canonical representation. That helps with 
comparing and searching for strings. The 'NFC' form is recommended for general text. 


Finding strings: 


e String.prototype.startsWith(searchString, position=0) : boolean 
Does the receiver start with searchString? position lets you specify where the string to 
be checked starts. 

e String.prototype.endsWith(searchString, endPosition=searchString.length) 

boolean 

Does the receiver end with searchString? endPosition lets you specify where the string 
to be checked ends. 

e String.prototype.includes(searchString, position=0) : boolean 
Does the receiver contain searchString? position lets you specify where the string to be 
searched starts. 


Repeating strings: 


e String.prototype.repeat(count) : string 
Returns the receiver, concatenated count times. 


?http://unicode.org/faq/normalization.html 


8. Symbols 


Symbols are a new primitive type in ECMAScript 6. This chapter explains how they work. 


8.1 Overview 


8.1.1 Use case 1: unique property keys 


Symbols are mainly used as unique property keys — a symbol never clashes with any other property 
key (symbol or string). For example, you can make an object iterable (usable via the for-of loop 
and other language mechanisms), by using the symbol stored in Symbol. iterator as the key of a 
method (more information on iterables is given in the chapter on iteration): 


let iterableObject = { 
[Symbol.iterator]() { // (A) 
let data = ['hello', 'world']; 
let index = 0; 
return { 
next() { 
if (index < data.length) ( 
return { value: data[index++] 7; 
} else { 
return { done: true }; 


} 


$; 
} 
} 
for (let x of iterableObject) { 
console. log(x) ; 
} 
// Output: 
// hello 
// world 


In line A, a symbol is used as the key of the method. This unique marker makes the object iterable 
and enables us to use the for-of loop. 
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8.1.2 Use case 2: constants representing concepts 


In ECMAScript 5, you may have used strings to represent concepts such as colors. In ES6, you can 
use symbols and be sure that they are always unique: 


const COLOR_RED = Symbol(); 
const COLOR_ORANGE = Symbol(); 
const COLOR_YELLOW = Symbol(); 
const COLOR_GREEN = Symbol(); 
const COLOR_BLUE = Symbol(); 
const COLOR_VIOLET = Symbol(); 


function getComplement(color) { 
switch (color) { 
case COLOR_RED: 
return COLOR_GREEN; 
case COLOR_ORANGE: 
return COLOR_BLUE; 
case COLOR_YELLOW: 
return COLOR_VIOLET; 
case COLOR_GREEN: 
return COLOR_RED; 
case COLOR_BLUE: 
return COLOR_ORANGE; 
case COLOR_VIOLET: 
return COLOR_YELLOW; 
default: 
throw new Exception('Unknown color: '+color); 


8.2 A new primitive type 


ECMAScript 6 introduces a new primitive type: symbols. They are tokens that serve as unique IDs. 
You create symbols via the factory function Symbol () (which is loosely similar to String returning 
strings if called as a function): 


let symbol1 = Symbol(); 


Symbol() has an optional string-valued parameter that lets you give the newly created Symbol a 
description: 
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> let symbol2 = Symbol('symbol2'); 
> String(symbol2) 
"Symbol (symbol2)' 


Every symbol returned by Symbol () is unique, every symbol has its own identity: 


> Symbol() === Symbol() 
false 


You can see that symbols are primitive if you apply the typeof operator to one of them - it will 
return a new symbol-specific result: 


> typeof Symbol() 
'symbol' 


8.2.1 Symbols as property keys 


Symbols can be used as property keys: 


const MY_KEY = Symbol(); 
let obj = {}; 


obj [MY_KEY] = 123; 
console.log(obj[MY_KEY]); // 123 


Classes and object literals have a feature called computed property keys: You can specify the key of 
a property via an expression, by putting it in square brackets. In the following object literal, we use 
a computed property key to make the value of MY_KEY the key of a property. 


const MY_KEY = Symbol(); 
let obj = ( 

[MY_KEY]: 123 
$; 


A method definition can also have a computed key: 
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const FOO = Symbol(); 
let obj = { 
[FOO}]() { 


return 'bar'; 


35 
console. log(obj [FOO]()); // bar 


8.2.2 Enumerating own property keys 


Given that there is now a new kind of value that can become the key of a property, the following 
terminology is used for ECMAScript 6: 


e Property keys are either strings or symbols. 
e String-valued property keys are called property names. 


e Symbol-valued property keys are called property symbols. 


Let’s examine the API for enumerating own property keys by first creating an object. 


let obj = { 
[Symbol('my_key')]: 1, 
enum: 2, 


nonEnum: 3 
$5 
Object.defineProperty (obj, 
'nonEnum', { enumerable: false }); 


Object. getOwnPropertyNames() ignores symbol-valued property keys: 


> Object. getOwnPropertyNames (obj) 
['enum', 'nonEnum'] 


Object. getOwnPropertySymbols() ignores string-valued property keys: 


> Object. getOwnPropertySymbols (obj) 
[Symbol (my_key) ] 


Reflect.ownKeys () considers all kinds of keys: 
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> Reflect.ownKeys(obj) 
[Symbol (my_key), 'enum', 'nonEnum' ] 


Object.keys() only considers enumerable property keys that are strings: 


> Object.keys(obj) 
['enum' ] 


The name Object.keys clashes with the new terminology (only string-valued keys are listed). 
Object.names or Object. getEnumerableOwnPropertyNames would be a better choice now. 


8.3 Using symbols to represent concepts 


In ECMAScript 5, one often represents concepts (think enum constants) via strings. For example: 


var COLOR_RED = 'RED'; 
var COLOR_ORANGE = 'ORANGE'; 
var COLOR_YELLOW = 'YELLOW'; 
var COLOR_GREEN = 'GREEN'; 
var COLOR_BLUE = 'BLUE'; 
var COLOR_VIOLET "VIOLET"; 


However, strings are not as unique as we'd like them to be. To see why, let's look at the following 
function. 


function getComplement(color) { 
switch (color) { 
case COLOR_RED: 
return COLOR_GREEN; 
case COLOR_ORANGE: 
return COLOR_BLUE; 
case COLOR_YELLOW: 
return COLOR_VIOLET; 
case COLOR_GREEN: 
return COLOR_RED; 
case COLOR_BLUE: 
return COLOR_ORANGE; 
case COLOR_VIOLET: 
return COLOR_YELLOW; 
default: 
throw new Exception('Unknown color: '+color); 
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It is noteworthy that you can use arbitrary expressions as switch cases, you are not limited in any 
way. For example: 


function isThree(x) { 
switch (x) { 
case 1 + 1 + 1: 
return true; 
default: 
return false; 


} 


We use the flexibility that switch offers us and refer to the colors via our constants (COLOR_RED 
etc.) instead of hard-coding them ('RED' etc.). 


Interestingly, even though we do so, there can still be mix-ups. For example, someone may define a 
constant for a mood: 


var MOOD_BLUE = 'BLUE'; 


Now the value of BLUE is not unique anymore and MOOD_BLUE can be mistaken for it. If you use it 
as a parameter for getComplement (), it returns 'ORANGE' where it should throw an exception. 


Let’s use symbols to fix this example. Now we can also use the ES6 feature const, which lets us 
declare actual constants (you can’t change what value is bound to a constant, but the value itself 
may be mutable). 


const COLOR_RED = Symbol(); 
const COLOR_ORANGE = Symbol(); 
const COLOR_YELLOW = Symbol(); 
const COLOR_GREEN = Symbol(); 
const COLOR_BLUE = Symbol(); 
const COLOR_VIOLET = Symbol(); 


Each value returned by Symbol is unique, which is why no other value can be mistaken for BLUE 


now. Intriguingly, the code of getComplement () doesn’t change at all if we use symbols instead of 
strings, which shows how similar they are. 


8.4 Symbols as keys of properties 


Being able to create properties whose keys never clash with other keys is useful in two situations: 


e If several parties contribute internal properties to the same object, via mixins. 
e To keep meta-level properties from clashing with base-level properties. 
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8.4.1 Symbols as keys of internal properties 


Mixins are object fragments (sets of methods) that you can use to augment the functionality of an 
object or a prototype. If their methods have symbols as keys, they can't clash with other methods 
(of other mixins or of the object that they are added to), anymore. 


Public methods are seen by clients of the object a mixin is added to. For usability’s sake, you probably 
want those methods to have string keys. Internal methods are only known to the mixin or only 
needed to communicate with it. They profit from having symbols as keys. 


Symbols do not offer real privacy, because it is easy to find out the symbol-valued property keys 
of an object. But the guarantee that a property key can't ever clash with any other property key is 
often enough. If you truly want to prevent the outside from accessing private data, you need to use 
WeakMaps or closures. For example: 


// One WeakMap per private property 
let _counter = new WeakMap() ; 
let _action = new WeakMap(); 
class Countdown { 
constructor (counter, action) ( 
_counter.set(this, counter); 
_action.set(this, action); 


} 

dec() { 
let counter = _counter.get(this) ; 
if (counter < 1) return; 
counter--; 
_counter.set(this, counter); 
if (counter === 0) ( 

_action.get(this)(); 

} 

} 


The instances of Countdown are keys in the WeakMaps _counter and _action. The WeakMap 
does not prevent the instances from being garbage-collected. Entries whose keys are objects that 
don’t exist anymore, are removed from WeakMaps. 


The same code looks as follows if you use a symbol key for the internal property. 
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const _counter = Symbol(); 
const _action = Symbol(); 
class Countdown { 
constructor (counter, action) ( 
this[_counter] = counter; 
this[_action] = action; 


} 

dec() 1 
let counter = this[_counter]; 
if (counter < 1) return; 
counter--; 
this[_counter] = counter; 
if (counter === 0) ( 

this[_action](); 

} 

} 


8.4.2 Symbols as keys of meta-level properties 


Symbols having unique identities makes them ideal as keys of public properties that exist on a 
different level than “normal” property keys, because meta-level keys and normal keys must not 
clash. One example of meta-level properties are methods that objects can implement to customize 
how they are treated by a library. Using symbol keys protects the library from mistaking normal 
methods as customization methods. 


Iterability in ECMAScript 6 is one such customization. An object is iterable if it has a method whose 
key is the symbol (stored in) Symbol. iterator. In the following code, obj is iterable. 


let obj = { 
data: [ 'hello', 'world' ], 
[Symbol .iterator]() 4 
const self = this; 
let index = 0; 


return ( 
next() { 
if (index < self.data.length) { 
return { 
value: self.data[index++] 
$; 
} else ( 


return { done: true }; 
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}; 
}; 
The iterability of obj enables you to use the for-of loop and similar JavaScript features: 


for (let x of obj) { 
console. log(x) ; 


// Output: 
// hello 
// world 


8.5 Crossing realms with symbols 


A code realm (short: realm) is a context in which pieces of code exist. It includes global variables, 
loaded modules and more. Even though code exists “inside” exactly one realm, it may have access 
to code in other realms. For example, each frame in a browser has its own realm. And execution can 
jump from one frame to another, as the following HTML demonstrates. 


<head> 
<script> 
function test(arr) ( 
var iframe = frames[0]; 
// This code and the iframe’s code exist in 
// different realms. Therefore, global variables 
// such as Array are different: 
console. log(Array === iframe.Array); // false 
console.log(arr instanceof Array); // false 
console.log(arr instanceof iframe.Array); // true 
// But: symbols are the same 
console. log(Symbol.iterator === 
iframe.Symbol.iterator); // true 
hi 
</script> 
</head> 
<body> 


<iframe srcdoc="<script>window.parent.test([])</script>"> 
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</iframe> 
</body> 


The problem is that each realm has its own local copy of Array and, because objects have individual 
identities, those local copies are considered different, even though they are essentially the same 
object. Similarly, libraries and user code are loaded once per realm and each realm has a different 
version of the same object. 


In contrast, members of the primitive types boolean, number and string don’t have individual 
identities and multiple copies of the same value are not a problem: The copies are compared “by 
value” (by looking at the content, not at the identity) and are considered equal. 


Symbols have individual identities and thus don’t travel across realms as smoothly as other primitive 
values. That is a problem for symbols such as Symbol. iterator that should work across realms: 
If an object is iterable in one realm, it should be iterable in others, too. If a cross-realm symbol is 
managed by the JavaScript engine, the engine can make sure that the same value is used in each 
realm. For libraries, however, we need extra support, which comes in the form of the global symbol 
registry: This registry is global to all realms and maps strings to symbols. For each symbol, libraries 
need to come up with a string that is as unique as possible. To create the symbol, they don’t use 
Symbol(), they ask the registry for the symbol that the string is mapped to. If the registry already 
has an entry for the string, the associated symbol is returned. Otherwise, entry and symbol are 
created first. 


You ask the registry for a symbol via Symbol. for () and retrieve the string associated with a symbol 
(its key) via Symbol. keyFor (): 


> let sym = Symbol.for('Hello everybody! '); 
> Symbol.keyFor (sym) 
"Hello everybody! ' 


As expected, cross-realm symbols, such as Symbol. iterator, that are provided by the JavaScript 
engine are not in the registry: 


> Symbol.keyFor (Symbol. iterator) 
undefined 


8.6 Wrapper objects for symbols 


While all other primitive values have literals, you need to create symbols by function-calling Symbol. 
Thus, it is relatively easy to accidentally invoke Symbol as a constructor. That produces instances 
of Symbol and is not very useful. Therefore, an exception is thrown when you try to do that: 
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> new Symbol() 
TypeError: Symbol is not a constructor 


There is still a way to create wrapper objects, instances of Symbol: Object, called as a function, 
converts all values to objects, including symbols. 


> let sym = Symbol(); 
> typeof sym 
' symbol ' 


> let wrapper = Object(sym); 
> typeof wrapper 

'object' 

> wrapper instanceof Symbol 
true 


8.6.1 Property access via [ ] 


The square bracket operator [ ] for accessing properties unwraps string wrapper objects and symbol 
wrapper objects. Let’s use the following object to examine this phenomenon. 


const sym = Symbol('yes'); 
let obj = { 

[sym]: 'a', 

str: 'b', 
$5 


Interaction: 


> let wrappedSymbol = Object(sym) ; 
> typeof wrappedSymbol 

‘object! 

> obj [wrappedSymbol] 

Lo 


> let wrappedString = new String('str'); 
> typeof wrappedString 

'object' 

> obj[wrappedString] 

tb? 
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8.6.1.1 Property access in the spec 


The operator for getting and setting properties uses the internal operation ToPropertyKey()’, 
which works as follows: 


e Convert the operand to a primitive via ToPrimitive()? with the preferred type string: 

— Primitive values are returned as is. 

— Most objects are converted via the method toString() - if it returns a primitive value. 
Otherwise, valueOf () is used — if it returns a primitive value. Otherwise, a TypeError 
is thrown. 

— Symbol objects are one exception: they are converted to the symbols that they wrap. 

e If the result is a symbol, return it. 
e Otherwise, coerce the result to string via ToString()?. 


8.7 Converting symbols to other primitive types 


The following table shows what happens if you explicitly or implicitly convert symbols to other 
primitive types: 


Conversionto Explicit conversion Coercion (implicit conversion) 
boolean Boolean(sym) — OK ! sym — OK 

number Number (sym) — TypeError sym*2 — TypeError 

string String(sym) — OK ''+sym — TypeError 


8.7.1 Pitfall: coercion to string 


Coercion to string being forbidden can easily trip you up: 


const sym = Symbol(); 


console. log('A symbol: '+sym); // TypeError 
console. log(’A symbol: ${sym}`); // TypeError 


To fix these problems, you need an explicit conversion to string: 


*http://www.ecma-international.org/ecma-262/6.0/#sec-topropertykey 
*http://www.ecma-international.org/ecma-262/6.0/#sec-toprimitive 
*http://www.ecma-international.org/ecma-262/6.0/#sec-tostring 
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console.log('A symbol: '+String(sym)); // OK 
console.log('A symbol: ${String(sym)}°); // OK 


8.7.2 Making sense of the coercion rules 
Coercion (implicit conversion) is often forbidden for symbols. This section explains why. 


8.7.2.1 Truthiness checks are allowed 


Coercion to boolean is always allowed, mainly to enable truthiness checks in if statements and 
other locations: 


if (value) { *:* } 
param = param || 0; 


8.7.2.2 Accidentally turning symbols into property keys 

Symbols are special property keys, which is why you want to avoid accidentally converting them 
to strings, which are a different kind of property keys. This could happen if you use the addition 
operator to compute the name of a property: 

myObject['__' + value] 


That’s why a TypeError is thrown if value is a symbol. 


8.7.2.3 Accidentally turning symbols into Array indices 


You also don’t want to accidentally turn symbols into Array indices. The following is code where 
that could happen if value is a symbol: 


myArray[1 + value] 
That's why the addition operator throws an error in this case. 


8.7.3 Explicit and implicit conversion in the spec 


8.7.3.1 Converting to boolean 


To explicitly convert a symbol to boolean, you call Boolean ()*, which returns true for symbols: 


“http://www.ecma-international.org/ecma-262/6.0/#sec-boolean-constructor-boolean-value 
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> const sym = Symbol('hello'); 
> Boolean(sym) 
true 


Boolean() computes its result via the internal operation ToBoolean()?, which returns true for 
symbols and other truthy values. 


Coercion also uses ToBoolean(): 


> lsym 
false 


8.7.3.2 Converting to number 


To explicitly convert a symbol to number, you call Number ()°: 


> const sym = Symbol('hello');3 
> Number (sym) 
TypeError: can't convert symbol to number 


Number () computes its result via the internal operation ToNumber ()”, which throws a TypeError 
for symbols. 


Coercion also uses ToNumber (): 


> +sym 
TypeError: can't convert symbol to number 


8.7.3.3 Converting to string 


To explicitly convert a symbol to string, you call String()*: 


> const sym = Symbol('hello');3 
> String (sym) 
"Symbol (hello) ' 


If the parameter of String() is a symbol then it handles the conversion to string itself and returns 
the string Symbol () wrapped around the description that was provided when creating the symbol. 
If no description was given, the empty string is used: 


*http://www.ecma-international.org/ecma-262/6.0/#sec-toboolean 
*http://www.ecma-international.org/ecma-262/6.0/#sec-number-constructor-number- value 
"http://www.ecma-international.org/ecma-262/6.0/#sec-tonumber 
Shttp://www.ecma-international.org/ecma-262/6.0/#sec-string-constructor-string-value 
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> String(Symbol()) 
"Symbol () ' 


The toString() method returns the same string as String(), but neither of these two operations 
calls the other one, they both call the same internal operation SymbolDescriptiveString()”. 


> Symbol ('hello').toString() 
"Symbol (hello) ' 


Coercion is handled via via the internal operation ToString()*”, which throws a TypeError for 
symbols. One method that coerces its parameter to string is Number .parseInt (): 


> Number .parselInt(Symbol()) 
TypeError: can't convert symbol to string 


8.7.3.4 Not allowed: converting via the binary addition operator (+) 


The addition operator“ works as follows: 


e Convert both operands to primitives. 


e If one of the operands is a string, coerce both operands to strings (via ToString()), 
concatenate them and return the result. 


e Otherwise, coerce both operands to numbers, add them and return the result. 


Coercion to either string or number throws an exception, which means that you can’t (directly) use 
the addition operator for symbols: 


> '' + Symbol () 
TypeError: can't convert symbol to string 
> 1 + Symbol() 
TypeError: can't convert symbol to number 


*http://www.ecma-international.org/ecma-262/6.0/#sec-symboldescriptivestring 
http://www.ecma-international.org/ecma-262/6.0/#sec-tostring 


“http://www.ecma-international.org/ecma-262/6.0/#sec-addition-operator-plus 
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8.8 JSON and symbols 


8.8.1 Generating JSON via ISON.stringify() 


JSON.stringify() converts JavaScript data to JSON strings. A preprocessing step lets you 
customize that conversion: a callback, a so-called replacer, can replace any value inside the JavaScript 
data with another one. That means that it can encode JSON-incompatible values (such as symbols 
and dates) as JSON-compatible values (such as strings). JSON. parse() lets you reverse this process 
via a similar mechanism”. 


However, stringify ignores non-string property keys, so this approach works only if symbols are 
property values. For example, like this: 


function symbolReplacer(key, value) { 

if (typeof value === 'symbol') { 

return '@@' + Symbol.keyFor(value) + '@@'; 

} 

return value; 
} 
const MY_SYMBOL = Symbol.for('http://example.com/my_symbol'); 
let obj = { [MY_SYMBOL]: 123 }; 


let str = JSON.stringify(obj, symbolReplacer); 
console. log(str); 


A symbol is encoded as a string by putting '@@' before and after the symbol’s key. Note that only 
symbols that were created via Symbol. for () have such a key. 


8.8.2 Parsing JSON via JSON. parse() 


JSON. parse() converts JSON strings to JavaScript data. A postprocessing step lets you customize 
that conversion: a callback, a so-called reviver, can replace any value inside the initial output with 
another one. That means that it can decode non-JSON data (such as symbols and dates) stored in 
JSON data (such as strings)”. This looks as follows. 


[Speaking JS] Details are explained in the chapter on JSON. 
"31 Speaking JS] The details are explained in the chapter on JSON. 
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const REGEX_SYMBOL_STRING = /*@@(.*)@@S$/;3 
function symbolReviver(key, value) { 
if (typeof value === 'string') { 
let match = REGEX_SYMBOL_STRING.test(value) ; 
if (match) { 
let symbolKey = match[1]; 
return Symbol. for(symbolkey) ; 


} 


return value; 


let parsed = JSON.parse(str, symbolReviver); 
console. log(parse); 


Strings that start and end with '@@' are converted to symbols by extracting the symbol key in the 
middle. 


8.9 FAQ: symbols 


8.9.1 Can | use symbols to define private properties? 


The original plan was for symbols to support private properties, but that feature was dropped, 
because it would have interacted badly with proxies. The chapter on classes explains your options 
for keeping data private in instances of classes: store it in constructor environments, in properties 
with marked keys or in WeakMaps. 


8.9.2 Are symbols primitives or objects? 


In some ways, symbols are like primitive values, in other ways, they are like objects: 


e Symbols are like strings (primitive values) w.r.t. what they are used for: as representations of 
concepts and as property keys. 
e Symbols are like objects in that each symbol has its own identity. 


What are symbols then — primitive values or objects? In the end, they were turned into primitives, 
for two reasons. 


First, symbols are more like strings than like objects: They are a fundamental value of the language, 
they are immutable and they can be used as property keys. Symbols having unique identities doesn't 
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necessarily contradict them being like strings: UUID algorithms produce strings that are quasi- 
unique. 


Second, symbols are most often used as property keys, so it makes sense to optimize the JavaScript 
specification and the implementations for that use case. Then many abilities of objects are 
unnecessary: 


e Objects can become prototypes of other objects. 
e Wrapping an object with a proxy doesn’t change what it can be used for. 
e Objects can be introspected: via instanceof, Object.keys(), etc. 


Them not having these abilities makes life easier for the specification and the implementations. 
There are also reports from the V8 team that when handling property keys, it is simpler to treat 
primitives differently than objects. 


8.9.3 Do we really need symbols? Aren't strings enough? 


In contrast to strings, symbols are unique and prevent name clashes. That is nice to have for tokens 
such as colors, but it is essential for supporting meta-level methods such as the one whose key 
is Symbol. iterator. Python uses the special name __iter__ to avoid clashes. You can reserve 
double underscore names for programming language mechanisms, but what is a library to do? With 
symbols, we have an extensibility mechanism that works for everyone. As you can see later, in the 
section on public symbols, JavaScript itself already makes ample use of this mechanism. 


There is one hypothetical alternative to symbols when it comes to clash-free property keys: use 
a naming convention. For example, strings with URLs (e.g. 'http: //example.com/iterator'). 
But that would introduce a second category of property keys (versus “normal” property names that 
are usually valid identifiers and don’t contain colons, slashes, dots, etc.), which is basically what 
symbols are, anyway. Thus it is more elegant to explicitly turn those keys into a different kind of 
value. 


8.9.4 Are JavaScript's symbols like Ruby's symbols? 


No, they are not. Ruby’s symbols are more like JavaScript’s string literals — which are immutable 
and often interned: If the same string literal appears in several locations, storage space is reused. 
JavaScript engines manage this via a table mapping string values to storage locations. 


8.10 The symbol API 


This section gives an overview of the ECMAScript 6 API for symbols. 
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8.10.1 The function Symbol 


e Symbol (description?) : symbol 
Creates a new symbol. The optional parameter description allows you to give the symbol 
a description, which is useful for debugging. 


Symbol is not intended to be used as a constructor — an exception is thrown if you invoke it via new. 


8.10.2 Well-known symbols 


Several well-known symbols” can be accessed via properties of Symbol. They are all used as 
property keys and enable you to customize how JavaScript handles an object. 


Customizing basic language operations: 


e Symbol.hasInstance (method) 
Lets an object C customize the behavior of x instanceof C. 

e Symbol. toPrimitive (method) 
Lets an object customize how it is converted to a primitive value. This is the first step whenever 
something is coerced to a primitive type (via operators etc.). 

e Symbol. toStringTag (string) 
Called by Object.prototype. toString to compute the default string description of an 
object obj: ‘[object ‘+obj[Symbol.toStringTag]+’]’. 


Iteration (explained in the chapter on iteration): 


e Symbol. iterator (method) 
Makes an object iterable. Returns an iterator. 


Regular expressions: Four string methods that have regular expression parameters are simply 
forwarded to those parameters. The methods that they are forwarded to have the following keys: 


e Symbol.match is used by String.prototype.match. 

e Symbol.replace is used by String.prototype. replace. 
e Symbol.search is used by String. prototype. search. 

e Symbol.split is used by String.prototype.split. 


Miscellaneous: 


“http://www.ecma-international.org/ecma-262/6.0/#sec-well-known-symbols 
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e Symbol .unscopables (Object) 
Lets an object hide some properties from the with statement. 

e Symbol.species (method) 
Helps with cloning Typed Arrays and instances of RegExp, ArrayBuffer and Promise. 
Details are explained in the chapter on classes. 

e Symbol. isConcatSpreadable (boolean) 
Indicates whether Array.prototype.concat should concatenate the indexed elements of 
an object or the object as an element. 


8.10.3 Global symbol registry 


If you want a symbol to be the same in all realms, you need to create it via the global symbol registry. 
The following method lets you do that: 


e Symbol.for(str) : symbol 
Returns the symbol whose key is the string str in the registry. If str isn't in the registry yet, 
a new symbol is created and filed in the registry under the key str. 


Another method lets you make the reverse look up and found out under which key a string is stored 
in the registry. This is may be useful for serializing symbols. 


e Symbol.keyFor(sym) : string 
returns the string that is associated with the symbol sym in the registry. If sym isn't in the 
registry, this method returns undefined. 


9. Template literals and tagged 
templates 


This chapter covers two new kinds of literals: template literals and tagged templates. 


9.1 Overview 
The following three things are different — despite names and appearances being similar: 


e Web templates (data): HTML with blanks to be filled in 
e Template literals (code): multi-line string literals plus interpolation 
e Tagged templates (code): function calls 


Template literals are string literals that can stretch across multiple lines and include interpolated 
expressions: 


const firstName = 'Jane'; 
console. log( Hello S{firstName}! 
How are you 

today?'); 


// Output: 
// Hello Jane! 
// How are you 
// today? 


Tagged templates are created by mentioning a function before a template literal. They lead to a 
function call where the prefix is called and the template literal supplies the parameters: 


> String.raw A \tagged\ template’ 
'A \\tagged\\ template' 
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9.2 Introduction 


Literals are syntactic constructs that produce values. Examples include string literals (which produce 
strings) and regular expression literals (which produce regular expression objects). ECMAScript 6 
has two new literals: 


e Template literals: are string literals with support for interpolation and multiple lines. 
e Tagged templates: are function calls whose parameters are provided via template literals. 


It is important to keep in mind that the names of template literals and tagged templates are slightly 
misleading. They have nothing to do with templates, as they are often used in web development: 
text files with blanks that can be filled in via (e.g.) JSON data. 


9.2.1 Template literals 


A template literal is a new kind of string literal that can span multiple lines and interpolate 
expressions (include their results). For example: 


const firstName = 'Jane'; 
console. log( Hello ${firstName}! 
How are you 

today?'); 

// Output: 

// Hello Jane! 


// How are you 
// today? 


The literal itself is delimited by backticks (`), the interpolated expressions inside the literal are 
delimited by ${ and }. Template literals always produce strings. 


9.2.2 Tagged templates 
The following is a tagged template (which is short for tagged template literal): 
tagFunction Hello S${firstName} ${lastName}!` 


Putting a template literal after an expression calls the expression. That is similar to the effect of 
parameter lists (comma-separated values in parentheses). The previous code executes the following 
function call (in reality, the function receives more information, but that is explained later): 
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tagFunction(['Hello ', ' ', '!'], firstName, lastName) 


Thus, the name before the content in backquotes is the name of a function to call, the tag function. 
The tag function receives two different kinds of data: 


e Template strings such as 'Hello '. 
e Substitutions such as firstName (delimited by a dollar sign and braces). A substitution can 
be any expression. 


Template strings are known statically (at compile time), substitutions are only known at runtime. 
The tag function can do with its parameters as it pleases: It can completely ignore the template 
strings, return values of any type, etc. 


9.3 Examples of using tagged templates 


To understand what tagged templates are good for, let's look at examples. You'll find that tagged 
templates allow you to implement custom embedded sub-languages (which are sometimes called 
domain-specific languages) with little effort, because JavaScript does much of the parsing for you. 
You only have to write a function that receives the results. 


Some of the following examples are borrowed from the original proposal’ for template literals and 
tagged templates, which refers to them via their old name, quasi-literals. 


9.3.1 Raw strings 


ES6 includes the tag function String.raw for raw strings, where backslashes have no special 
meaning: 


let str = String.raw This is a text 
with multiple Lines. 

Escapes are not interpreted, 

An is not a newline.’ ; 


9.3.2 Escaping parts of a regular expression 
There are two ways of creating regular expression instances. 


e Statically, via a regular expression literal: /*abc$/i 
e Dynamically, via the RegExp constructor: new RegExp('*abc$', i) 


If you use the latter, it is because you have to wait until runtime so that all necessary ingredients are 
available: You are usually concatenating regular expression fragments and text that is to be matched 
verbatim. The latter has to be escaped properly (dots, square brackets, etc.). A regular expression tag 
function escRegExp can help with this task: 


*http://wiki.ecmascript.org/doku.php?id=harmony:quasis 
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const NUMBER = escRegExp’ \d+(${localeSpecificDecimalPoint}\d+)?°; 


A simple implementation of escRegExp is shown later. 


9.3.3 Tagged templates for more powerful regular expressions 


Steven Levithan has given an example’ of how tagged templates could be used for his regular 
expression library XRegExp’. 


XRegExp is highly recommended if you are working with regular expressions. You get 
many advanced features, but there is only a small performance penalty — once at creation 
time — because XRegExp compiles its input to native regular expressions. 


Without tagged templates, you write code such as the following: 


var parts = '/2012/10/Page.html'.match(XRegExp( 
'A # match at start of string only \n' + 
'/ (?<year> [*/]+ ) # capture top dir name as year \n' + 
'/ (?<month> [4/]+ ) + capture subdir name as month \n' + 
'/ (2<title> [4/]+ ) + capture base name as title \n' + 
"\\.html? $ # .htm or .html file ext at end of path ', 'x' 
)); 


console. log(parts.year); // 2012 


We can see that XRegExp gives us named groups (year, month, title) and the x flag. With that 
flag, most whitespace is ignored and comments can be inserted. 


There are two reasons that string literals don’t work well here. First, we have to type every regular 
expression backslash twice, to escape it for the string literal. Second, it is cumbersome to enter 
multiple lines: Instead of adding strings, you could also end the line with a backslash. But that is 
brittle and you still have to explicitly add newlines via \n. These two problems go away with tagged 
templates: 


?https://gist.github.com/4222600 
Shttp://xregexp.com 
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var parts = '/2012/10/Page.html'.match(XRegExp.rx' 
^ # match at start of string only 
/ (?<year> [*/]+ ) # capture top dir name as year 
/ (?<month> [*/]+ ) # capture subdir name as month 
/ (?<title> [4/]+ ) # capture base name as title 
\.html? $ + .htm or .html file ext at end of path 
`); 


Tagged templates also let you insert values v via ${v}. Fd expect a regular expression library to 
escape strings and to insert regular expressions verbatim. For example: 


var str = 'really?'; 
var regex = XRegExp.rx' (${str})* 3 


This would be equivalent to 


var regex = XRegExp.rx' (really\?)* 5 


9.3.4 Query languages 


Example: 
S’a.${className} [href=~'//S{domain}/']° 


This is a DOM query that looks for all <a> tags whose CSS class is className and whose target is 
a URL with the given domain. The tag function $ ensures that the arguments are correctly escaped, 
making this approach safer than manual string concatenation. 


9.3.5 React JSX via tagged templates 


Facebook’s React user interface library* has the optional language extension RSX that enables you 
to embed HTML inside JavaScript. This extension can make your code more concise, but it also 
breaks compatibility with the rest of the JavaScript ecosystem. Jonathan Raphaelson has used tagged 
templates to implement an approximation of JSX. That looks as follows. 


“https://facebook.github.io/react/ 
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class EchoComponent { 


render() { 


return jsx' 
<div> 
<input 
ref='input' 
onChange='${this.handleChange}' 
defaultValue='S{this.state.value}' /> 
S{this.state.value} 
</div> 
; 
} 


} 
let comp = jsx`<${EchoComponent} />`; 
React.renderComponent(comp, document.body) ; 


You can check out the full example and the implementation of the tag function jsx on 
GitHub’. 


9.3.6 Text localization (L10N) 


This section describes a simple approach to text localization that supports different languages and 
different locales (how to format numbers, time, etc.). Given the following message. 


alert(msg' Welcome to ${siteName}, you are visitor 
number S${visitorNumber}:d!°); 


The tag function msg would work as follows. 


First, The literal parts are concatenated to form a string that can be used to look up a translation in 
a table. An example for a lookup string is: 


"Welcome to {0}, you are visitor number {1}!' 


An example for a translation to German is: 


*https://gist.github.com/lygaret/a68220defa69174bdec5 
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"Besucher Nr. {1}, willkommen bei {0}!' 


The English “translation” would be the same as the lookup string. 


Second, the result from the lookup is used to display the substitutions. Because a lookup result 
includes indices, it can rearrange the order of the substitutions. That has been done in German, 
where the visitor number comes before the site name. How the substitutions are formatted can be 
influenced via annotations such as : d. This annotation means that a locale-specific decimal separator 
should be used for visitorNumber. Thus, a possible English result is: 


Welcome to ACME Corp., you are visitor number 1,300! 
In German, we have results such as: 


Besucher Nr. 1.300, willkommen bei ACME Corp.! 


9.4 Implementing tag functions 
The following is a tagged template: 
tagFunction lit1\n${subst1} lit2 ${subst2}° 


This is transformed internally to a function call: 


{ 
// Globally: add template object to per-realm template map 
// “Cooked” template strings: backslash is interpreted 
const templateObject = ['litiln', ' lit2 ', '']; 
// “Raw” template strings: backslash is verbatim 
template0bject.raw = ety ya. Es e Ty TT]; 
// The Arrays with template strings are frozen 
Object.freeze(templateObject. raw) ; 
Object.freeze(templateObject) ; 
__templateMap__[716] = templateObject; 

t 


// In-place: invocation of tag function 
tagFunction(__templateMap__[716], subst1, subst2) 


Template literals and tagged templates 109 
The parameters of the tag function are split into two categories: 


1. The template object: where you get the template strings both with escapes such as \n 
interpreted (“cooked”) and uninterpreted (“raw”). The number of template strings is always 
one plus the number of substitutions. If a substitution is first in a literal, it is prefixed by an 
empty template string. If a substitution is last, it is suffixed by an empty template string (as 
in the previous example). 

2. The substitutions: whose values become trailing parameters. 


The idea is that the same literal might be executed multiple times (e.g. in a loop or a function). With 
the template object, the tag function can cache data from previous invocations: (1) is potentially 
cacheable data, (2) changes with each invocation. Caching happens per realm (think frame in a 
browser). That is, there is one template object per call site and realm. 


ol Tagged templates in the spec 


A section on tagged templates? explains how they are interpreted as function calls. A 
separate section” explains how a template literal is turned into a list of arguments: the 
template object and the substitutions. 


9.4.1 Escaping in tagged templates: cooked vs. raw 


In tagged templates, there are more rules for escaping, because template strings (the text fragments 
inside the backticks, excluding substitutions) are available in two interpretations: cooked and raw. 
The rules are: 


e In both cooked and raw interpretation, a backslash (1) in front of a dollar sign ($) prevents $4 
from being interpreted as starting a substitution. 


e However, every single backslash is mentioned in the raw interpretation, even the ones that 
escape substitutions. 


The tag function describe allows us to explore what that means. 


*http://www.ecma-international.org/ecma-262/6.0/#sec-tagged-templates 
"http://www.ecma-international.org/ecma-262/6.0/#sec-template-literals-runtime-semantics-argumentlistevaluation 
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function describe(tmpl0bj, ...substs) ( 
console.log('Cooked:', intersperse(tmpl0bj, substs)); 
console.log('Raw: ', intersperse(tmplObj.raw, substs)); 
} 


function intersperse(tmplStrs, substs) ( 
// There is always at least one element in tmplStrs 
let result = tmplStrs[0]; 
substs.forEach((subst, i) => { 
result += String(subst) ; 
result += tmplStrs[i+1]; 
$; 


return result; 


Let's use this tag function (I am not showing the result undefined of these function calls): 


> describe’ ${3+3}° 
Cooked: 6 
Raw: 6 


> describe’ \${3+3}° 
Cooked: S${3+3} 
Raw: \${3+3} 


> describe \\${3+3}° 
Cooked: \6 
Raw: \\6 


> describe \\\${3+3}- 
Cooked: 1513+3) 
Raw: \\\S {3+3} 


As you can see, whenever the cooked interpretation has a substitution then so does the raw 
interpretation. However, all backslashes from the literal appear in the raw interpretation; if a 
backslash precedes the characters ${ then it prevented a substitution. 


Other occurrences of the backslash are interpreted similarly: 


e In cooked mode, the backslash is handled like in string literals. 
» In raw mode, the backslash is used verbatim. 


For example: 
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> “An” 
in! 
> String.raw \n° 


Han” 


The only time the backslash ever has an effect in raw mode is when it appears in front of a 
substitution (which it escapes). 


+ Escaping in tagged templates in the spec 


In the grammar for template literals*, you can see that, within a template literal, there must 
be no open curly brace ({) after a dollar sign ($). However, an escaped dollar sign (1$) can 
be followed by an open curly brace. The rules for interpreting the characters of a template 
literal are explained in a separate section”. 


9.4.2 Example: implementing a tag function for HTML templating 


In this section, I explain how you can use tagged templates for HTML templating. The approach is 
based on an idea’® by Claus Reinke. 


9.4.2.1 Defining and using an HTML template 


You define an HTML template as follows. It relies on the tag function html (which is shown later). 


const tmpl = addrs => html" 
<table> 
S{addrs.map(addr => html” 
<tr>sS{addr.first}</tr> 
<tr>sSf{addr.last}</tr> 
`)} 
</table> 


The trick is that the the inside of each substitution ${} can be an arbitrary expression. We use map () 
to create an Array of strings inside the first substitution (which html () turns into the appropriate 
string). Thanks to arrow functions, the callback of map () is nicely concise. 


Inside the callback, we are “invoking” html again. Therefore, calling the function tmp1 leads to 
several calls of the function html. 


Shttp://www.ecma-international.org/ecma-262/6.0/#sec-template-literal-lexical-components 
*http://www.ecma-international.org/ecma-262/6.0/#sec-static- semantics-tv-and-trv 
?https://mail.mozilla.org/pipermail/es-discuss/2012- August/024328.html 
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The double dollar sign in $${addr.last} is not ES6 syntax, it is simply the normal text “$” in 
front of the substitution $faddr. last). But the tag function treats a substitution differently if it is 
preceded by a dollar sign — it HTML-escapes the string returned by it. 


The template is used like this: 


console. log(tmpl([ 
{ first: '<Jane>', last: 'Bond' }, 
{ first: 'Lars', last: '<Croft>' }, 
1035 
This code produces the following output: 


<table> 


<tr>Jane</tr> 
<tr>&lt;Bond&gts </tr> 


<tr>-&ltsLars&gt; </tr> 
<tr>Croft</tr> 


</table> 
Note that the angle brackets around Jane and Croft are escaped, whereas <tr> isn't. 


9.4.2.2 The tag function 


The tag function is surprisingly simple: 


function html(templateObject, ...substs) { 
// Use raw template strings: we don’t want 
// backslashes (\n etc.) to be interpreted 
let raw = templateObject.raw; 


let result = ''; 

substs.forEach((subst, i) => ( 
// Retrieve the template string preceding 
// the current substitution 


let lit = raw[i]; 


// In the example, map() returns an Array: 
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}); 
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// 


II 
if 


If substitution is an Array (and not a string), 
we turn it into a string 

(Array.isArray(subst)) { 

subst = subst.join(''); 


If the substitution is preceded by a dollar sign, 
we escape special characters in it 
(lit.endswith('s')) { 

subst = htmlEscape(subst) ; 

lit = lit.slice(0, -1); 
t 

result += 
result += 


lit; 
subst; 


// Take care of last template string 

// (Never fails, because an empty tagged template 
// produces one template string, an empty string) 
result += raw[raw.length-1]; // (A) 


return result; 


Each substitution is always surrounded by template strings. If the tagged template ends with a 
substitution, the last template string is an empty string. Accordingly, the following expression is 


always true: 


templateObject. length === substs.length + 1 


That’s why we need to append the last template string in line A. 


The following is a simple implementation of htmlEscape (). 


function htmlEscape(str) { 
return str.replace(/2/g, 
.replace(/>/g, 
.replace(/</g, 
.replace(/"/g, 
.replace(/'/g, 
.replace(/' /g, 


'&amp;') // first! 
'&gt;') 

"&lt;') 

"&quot;') 

"&#393') 

'&#96;'); 
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9.4.2.3 More ideas 


There are more things you can do with this approach to templating: 


e This approach isn’t limited to HTML, it would work just as well for other kinds of text. 
Obviously, escaping would have to be adapted. 

e if-then-else inside the template can be done via the ternary operator (cond?then: else) or 
via the logical Or operator (| |): 


SS{addr.first ? addr.first : '(No first name)') 
$Sf{addr.first || '(No first name)') 


e Some of the leading whitespace in each line can be trimmed if the first non-whitespace 
character in the first line defines where the first column is. 
e Destructuring can be used: 


S{addrs.map(({first,last}) => html” 
<tr>ss{first}</tr> 
<tr>ss{last}</tr> 

ee: 


9.4.2.4 Should I use this in production code? 


Use this approach if you need something quick and dirty. It is not as readable as the template syntax 
supported by Handlebars.js** and similar templating engines. On the other hand, it is lightweight 
and control flow mechanisms (loops and if-then-else) are easy to understand, because they are just 
JavaScript. 


9.4.3 Example: quoting parts of regular expressions 


Let’s implement the previously mentioned tag function escRegExp that assembles a regular 
expression while escaping substitutions. 


“http://handlebarsjs.com/ 
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function escRegExp(tmpl0bj, ...substs) { 
// Template strings are used verbatim 
let regexText = tmplObj.raw[0]; 
for ([i, subst] of substs.entries()) { 
regexText += quoteText(String(subst) ) ; 
regexText += tmplObj.raw[it+1]; 
} 
return new RegExp(regexText); 
} 
function quoteText(text) { 
return text.replace(/[\\%$.*+?() [\]{}]=!<>:-]/g, 
} 


This is escRegExp in use: 


// Note the single backslashes 
let re = escRegExp’\S$S{dot}\$°; 
fy te = SNS] 
re.test('S.$')3 // true 
re.test('$_$'); // false 


9.5 FAQ: template literals and tagged templates 


9.5.1 Where do template literals and tagged literals come from? 


"\\$&") 5 
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Template literals and tagged templates were borrowed from the language E, which calls this feature 


quasi literals”. 


9.5.2 What is the difference between macros and tagged 


templates? 


Macros allow you to implement constructs that have custom syntax. Providing macros for a language 
whose syntax is as complex as JavaScript’s is difficult and ongoing research (see Mozilla’s sweet.js*’). 


While macros are much more powerful for implementing sub-languages than tagged templates, they 
depend on the tokenization of the language. Therefore, tagged templates are complementary, because 


they specialize on text content. 


“http://www.erights.org/elang/grammar/quasi-overview.html 
http://sweetjs.org/ 


Template literals and tagged templates 116 


9.5.3 Can I load a template literal from an external source? 


What if I want to load a template literal such as ‘Hello ${name} !` from an external source (e.g., 
a file)? 


Note that you are abusing this mechanism if you do so. Given that a template literal can contain 
arbitrary expressions and is a literal, loading it from somehwere else is similar to loading an 
expression or a string literal — you have to use eval() or something similar. 


Coming back to the example, this is how you'd do it: 


let str = ''Hello ${name}!°'; // external source 
let func = new Function('name', str); 


let name = 'Jane'; 
let result = func(name) ; 


Every variable that isn’t declared inside the template literal has to become a parameter of the 
function func that we are creating. Alternatively, you could load a whole function and eval it'*: 


let str = '(name) => ‘Hello ${name}!°'; // external source 
let func = eval.call(null, str); // indirect eval 


let name = 'Jane'; 
let result = func(name) ; 


9.5.4 Why are backticks the delimiters for template literals and 
tagged templates? 


The backtick was one of the few ASCII characters that were still unused. The syntax ${} for 
interpolation is the de-facto standard (Unix shells, etc.). 


9.5.5 Weren't template literals once called template strings? 


The template literal terminology changed relatively late during the creation of the ES6 spec. The 
following are the old terms: 


e Template string (literal): the old name for template literal. 

e Tagged template string (literal): the old name for tagged template. 

e Template handler: the old name for tag function. 

e Literal section: the old name for template string (the term substitution remains the same). 


“(Speaking JS] http://speakingjs.com/es5/ch23.html*_dynamically_evaluating_ javascript_code_via_eval_and_new_function 


10. Variables and scoping 


This chapter examines how variables and scoping are handled in ECMAScript 6. 


10.1 Overview 


ES6 provides two new ways to declare variables: let and const, which mostly replace the ES5 way 
of declaring variables, var. 


10.1.1 let 


let works similarly to var, but the variable it declares is block-scoped, it only exists within the 
current block. var is function-scoped. 


In the following code, you can see that the let-declared variable tmp only exists with the block that 
starts in line A: 


function order(x, y) { 
if (x > y) { // (A) 
let tmp = x; 
x = y; 
y = tmp; 
} 
console.log(tmp===x); // ReferenceError: tmp is not defined 
return [x, y]; 


10.1.2 const 


const works like let, but the variable you declare must be immediately initialized, with a value 
that can't be changed afterwards. 
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const foo; 
// SyntaxError: missing = in const declaration 


const bar = 123; 


bar = 456; 
// TypeError: `barò is read-only 


10.1.3 Ways of declaring variables 


The following table gives an overview of six ways in which variables can be declared in ES6: 


Hoisting Scope Creates global properties 
var Declaration Function Yes 
let Temporal dead zone Block No 
const Temporal dead zone Block No 
function Complete Block Yes 
class No Block No 
import Complete Module-global No 


10.2 Block scoping via Let and const 


Both let and const create variables that are block-scoped — they only exist within the innermost 
block that surrounds them. The following code demonstrates that the let-declared variable tmp 
only exists inside the then-block of the if statement: 


function func() { 
if (true) { 
let tmp = 123; 
} 


console. log(tmp); // ReferenceError: tmp is not defined 


In contrast, var-declared variables are function-scoped: 
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function func() { 
if (true) { 
var tmp = 123; 
y 
console.log(tmp); // 123 


Block scoping means that you can shadow variables within a function: 


function func() { 
let foo = 5; 
if (se) { 
let foo = 10; // shadows outer `foo` 
console. log(foo); // 10 


} 
console. lLog(foo); // 5 


} 


10.3 const creates immutable variables 
Variables created by let are mutable: 


let foo = 'abc'; 
foo = 'def'; 
console. log(foo); // def 


Constants, variables created by const, are immutable — you can’t assign them a different value: 


const foo = 'abc'; 
foo = 'def'; // TypeError 


10.3.1 Pitfall: const does not make the value immutable 


const only means that a variable always has the same value, but it does not make a mutable value 
immutable. For example, obj is a constant, but the value it points to is mutable — we can add a 
property to it: 
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const obj = {}; 
obj.prop = 123; 
console.log(obj.prop); // 123 


We cannot, however assign a different value to obj: 
obj = {}; // TypeError 


If you want the value of obj to be immutable, you have to take care of it, yourself, e.g. by freezing 
i: 


const obj = Object.freeze({}); 
obj.prop = 123; // TypeError 


10.3.2 const in loop bodies 


Once a const variable has been created, it can’t be changed. But that doesn’t mean that you can’t 
re-enter its scope and start fresh, with a new value. For example, via a loop: 


function logArgs(...args) { 
for (let [index, elem] of args.entries()) { 
const message = index + '. ' + elem; 
console.log(message) ; 


} 
logArgs('Hello', 'everyone'); 


// Output: 
// 0. Hello 
// 1. everyone 


10.4 The temporal dead zone 


A variable declared by let or const has a so-called temporal dead zone (TDZ): When entering its 
scope, it can't be accessed (got or set) until execution reaches the declaration. 


Let's first examine the life cycle of var variables, which don't have temporal dead zones: 


*http://speakingjs.com/es5/ch17.html#freezing_objects 
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e When the scope (its surrounding function) of a var variable is entered, storage space (a 
so-called binding) is created for it. The variable is immediately initialized, by setting it to 
undefined. 

e When the execution within the scope reaches the declaration, the variable is set to the value 
specified by the initializer (an assignment) — if there is one. If there isn't, the value value of 
the variable remains undefined. 


Variables declared via let have temporal dead zones, which means that their life cycles look like 
this: 


e When the scope (its surrounding block) of a Let variable is entered, storage space (a so-called 
binding) is created for it. The variable remains uninitialized. 

e Getting or setting an uninitialized variable causes a ReferenceError. 

e When the execution within the scope reaches the declaration, the variable is set to the value 
specified by the initializer (an assignment) — if there is one. If there isn’t, the value of the 
variable is set to undefined. 


const variables work similarly to let variables, but they must have an initializer (i.e., be set to a 
value immediately) and can't be changed. 


Within a TDZ, an exception is thrown if a variable is got or set: 


if (true) { // enter new scope, TDZ starts 
// Uninitialized binding for 'tmp' is created 


tmp = 'abc'; // ReferenceError 
console.log(tmp); // ReferenceError 


let tmp; // TDZ ends, ‘tmp’ is initialized with ‘undefined’ 
console.log(tmp); // undefined 


tmp = 123; 
console. log(tmp); // 123 


The following example demonstrates that the dead zone is really temporal (based on time) and not 
spatial (based on location): 
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if (true) { // enter new scope, TDZ starts 
const func = function () ( 
console.log(myVar); // OK! 
35 


// Here we are within the TDZ and 
// accessing 'myVar” would cause a 'ReferenceError' 


let myVar = 3; // TDZ ends 
func(); // called outside TDZ 


10.4.1 typeof and the temporal dead zone 


A variable being unaccessible in the temporal dead zone means that you can't even apply typeof 
to it: 


if (true) { 


console. lLog(typeof tmp); // ReferenceError 
let tmp; 


I don’t expect this to be a problem for most programmers: Checking whether a variable exists in 
this manner is mainly done in libraries (especially polyfills). If a temporal dead zone becomes a 
problem, you can work around it (e.g. via window). Lastly, modules will reduce the need for this 
kind of trickery in the long run. 


10.5 Let and const in loop heads 
The following loops allow you to declare variables in their heads: 
e for 
e for-in 


e for-of 


To make a declaration, you can use either var, let or const. Each of them has a different effect, as 
Pll explain next. 


10.5.1 for loop 


var-declaring a variable in the head of a for loop creates a single binding for that variable: 
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let arr = []; 
for (var i=0; i < 3; i++) ( 
arr.push(() => 1); 


arr.map(x => x())3 // [3,3,3] 


Every i in the bodies of the three arrow functions refers to the same binding, which is why they all 
return the same value. 


If you let-declare a variable, a new binding is created for each loop iteration: 


let arr = []; 

for (let i=0; i < 3; i++) { 
arr.push(() => 1); 

} 

arr.map(x => x())3 // [0,1,2] 


This time, each i refers to the binding of one specific iteration and preserves the value that was 
current at that time. Therefore, each arrow function returns a different value. 


const works like var, but you can’t change the initial value of a const-declared variable. 


Getting a fresh binding for each iteration may seem strange at first, but it is very useful whenever 
you use loops to create functions (e.g. callbacks for event handling) that refer to loop variables. 


ro for loop: per-iteration bindings in the spec 


The evaluation of the for loop? handles var as the second case and let/const as 
the third case. Only let-declared variables are added to the list perIterationLets 
(step 9), which is passed to ForBodyEvaluation()? as the second-to-last parameter, 
perIterationBindings. 


10.5.2 for—of loop and for-in loop 


In a for-of loop, var creates a single binding: 


?http://www.ecma-international.org/ecma-262/6.0/*sec-for-statement-runtime-semantics-labelledevaluation 
*http://www.ecma-international.org/ecma-262/6.0/#sec-forbodyevaluation 
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let arr = []; 

for (var i of [0, 1, 2]) { 
arr.push(() => 1); 

} 

arr.map(x => x())3 // [2,2,2] 


let creates one binding per iteration: 


let arr = []; 

for (let i of [0, 1, 2]) { 
arr.push(() => 1); 

} 

arr.map(x => x())3 // [0,1,2] 


const also creates one binding per iteration, but the bindings it creates are immutable. 


The for-in loop works similarly to the for-of loop. 


Foe for-of loop: per-iteration bindings in the 
+ spec 


Per-iteration bindings in for-of are handled by ForIn/OfBodyEvaluation”. In step 5.b, 
a new environment is created and bindings are added to it via BindingInstantiation? 
(mutable for Let, immutable for const). The current iteration value is stored in the variable 
nextValue and used to initialize the bindings in either one of two ways: 


e Declaration of single variable (step 5.hi): is handled via 
InitializeReferencedBinding® 

e Destructuring (step 5.iiii): is handled via one case of BindingInitialization’ 
(ForDeclaration), which invokes another case of BindingInitialization® 
(BindingPattern). 


10.6 Parameters 


10.6.1 Parameters versus local variables 


If you let-declare a variable that has the same name as a parameter, you get a static (load-time) 
error: 


“http://www.ecma-international.org/ecma-262/6.0/#sec-runtime-semantics-forin-div-ofbodyevaluation-lhs-stmt-iterator-lhskind-labelset 
*http://www.ecma-international.org/ecma-262/6.0/#sec-runtime-semantics-bindinginstantiation 
*http://www.ecma-international.org/ecma-262/6.0/#sec-initializereferencedbinding 
"http://www.ecma-international.org/ecma-262/6.0/*sec-for-in-and-for-of-statements-runtime-semantics-bindinginitialization 
Shttp://www.ecma-international.org/ecma-262/6.0/*sec-destructuring-binding-patterns-runtime-semantics-bindinginitialization 
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function func(arg) { 
let arg; // static error: duplicate declaration of ‘arg’ 


Doing the same inside a block shadows the parameter: 


function func(arg) { 


{ 


let arg; // shadows parameter ‘arg’ 


In contrast, var-declaring a variable that has the same name as a parameter does nothing, just like 
re-declaring a var variable within the same scope does nothing. 


function func(arg) { 
var arg; // does nothing 


function func(arg) { 


{ 


// We are still in same ‘var’ scope as ‘arg’ 
var arg; // does nothing 


10.6.2 Parameter default values and the temporal dead zone 


If parameters have default values, they are treated like a sequence of let statements and are subject 
to temporal dead zones: 
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// OK: `y`ò accesses 'x' after it has been declared 
function foo(x=1, y=x) { 
return [x, y]; 
} 
foo(); // [1,1] 


// Exception: 'x' tries to access `y` within TDZ 
function bar(x=y, y=2) { 
return [x, y]; 


} 


bar(); // ReferenceError 


10.6.3 Parameter default values don't see the scope of the body 


The scope of parameter default values is separate from the scope of the body (the former surrounds 
the latter). That means that methods or functions defined “inside” parameter default values don’t 
see the local variables of the body: 


let foo = 'outer'; 

function bar(func = x => foo) { 
let foo = 'inner'; 
console.log(func()); // outer 

} 

bar (); 


10.7 The global object 


JavaScript's global object” (window in web browsers, global in Node.js) is more a bug than a 
feature, especially with regard to performance. That's why it's not surprising that ES6 introduces a 
distinction: 


e All properties of the global object are global variables. In global scope, the following 
declarations create such properties: 
— var declarations 
— Function declarations 
e But there are now also global variables that are not properties of the global object. In global 
scope, the following declarations create such variables: 
— let declarations 
- const declarations 
— Class declarations 


*http://speakingjs.com/es5/ch16.html#global_object 
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10.8 Function declarations and class declarations 


Function declarations... 


e are block-scoped, like let. 

e create properties on the global object (while in global scope), like var. 

e are hoisted: independently of where a function declaration is mentioned in its scope, it is 
always created at the beginning of the scope. 


The following code demonstrates the hoisting of function declarations: 


{ // Enter a new scope 


console. log(foo()); // OK, due to hoisting 
function foo() { 
return 'hello'; 


Class declarations... 


e are block-scoped. 
e don’t create properties on the global object. 
e are not hoisted. 


Classes not being hoisted may be surprising, because, under the hood, they create functions. The 
rationale for this behavior is that the values of their extends clauses are defined via expressions 
and those expressions have to be executed at the appropriate times. 


{ // Enter a new scope 
const identity = x => x; 


// Here we are in the temporal dead zone of 'MyClass' 
let inst = new MyClass(); // ReferenceError 


// Note the expression in the ‘extends’ clause 
class MyClass extends identity(Object) { 
} 
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10.9 Coding style: var vs. let vs. const 


var can do one thing that let and const can't: variables declared via it become properties of the 
global object. But the same effect can be achieved by assigning to window (in browsers) or global 
(in Node.js). Therefore, I recommend to always use let and const. 


Use const for things that are completely immutable: 


// Primitive values are immutable 
const PUBLIC_SYMBOL = Symbol (); 
const MAX_ENTRIES = 1000; 


// Some objects are immutable 
const EMPTY_ARRAY = Object.freeze([]); 


Use let for mutable things: 


// A primitive whose value changes 
let counter = 0; 
counter++; 


// A mutable object 
let obj {}3 
obj . foo 123; 


This is not a hard and fast rule. I don't see a problem with using const for a mutable object. 


11. Destructuring 


ECMAScript 6 supports destructuring, a convenient way to extract values from data stored in 
(possibly nested) objects and Arrays. This chapter describes how it works and gives examples of 
its usefulness. 


11.1 Overview 


In locations that receive data (such as the left-hand side of an assignment), destructuring lets you 
use patterns to extract parts of that data. 


The following code is an example of destructuring: 


let obj = { first: 'Jane', last: 'Doe' }; 
let { first: f, last: l } = obj; // (A) 
// f = 'Jane'; l = 'Doe' 


In line A we destructure obj: we extract data from it via a pattern on the left-hand side of 
the assignment operator (=) and assign that data to the variables f and 1. These variables are 
automatically declared beforehand, because the line starts with a let. 


You can destructure Arrays, too: 

let Eo y] = Plat, "b']3 // x = vars y = bp! 
Destructuring can be used in the following locations: 

// Variable declarations: 

let [x] = ['a']; 

const [x] = ['a']; 


var [x] = ['a']; 


// Assignments: 


[x] = [*a"]; 

// Parameter definitions: 
function f([x]) { --: } 
f(['a']); 


You can also destructure in a for-of loop: 


129 
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// Handled like a variable declaration: 
for (let [k,v] of arr.entries()) 


// Handled like an assignment 
for ({name: n, age: a} of arr) 


11.2 Background: Constructing data (object and Array 
literals) vs. extracting data (destructuring) 


To fully understand what destructuring is, let’s first examine its broader context. JavaScript has 
operations for constructing data: 


let obj = {}; 
obj.first = 'Jane'; 
obj.last = 'Doe'; 


And it has operations for extracting data: 


let f obj.first; 
let l = obj.last; 


Note that we are using the same syntax that we have used for constructing. 


There is nicer syntax for constructing — an object literal: 
let obj = { first: 'Jane', last: 'Doe' }; 


Destructuring in ECMAScript 6 enables the same syntax for extracting data, where it is called an 
object pattern: 


let { first: f, last: l } = obj; 


Just as the object literal lets us create multiple properties at the same time, the object pattern lets us 
extract multiple properties at the same time. 


You can also destructure Arrays via patterns: 


let [x, y] = ['a', 'b']; // x = 'a'; y = 'b' 
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11.3 Patterns 


The following two parties are involved in destructuring: 


e Destructuring source: the data to be destructured. For example, the right-hand side of a 
destructuring assignment. 

e Destructuring target: the pattern used for destructuring. For example, the left-hand side of 
a destructuring assignment. 


The destructuring target is either one of three patterns: 
e Assignment target. For example: x 
— In variable declarations and parameter definitions, only references to variables are 
allowed. In destructuring assignment, you have more options, as Pll explain later. 
e Object pattern. For example: { first: «pattern», last: «pattern» } 
— The parts of an object pattern are properties, the property values are again patterns 
(recursively). 


e Array pattern. For example: [ «pattern», «pattern» ] 
— The parts of an Array pattern are elements, the elements are again patterns (recursively). 


That means that you can nest patterns, arbitrarily deeply: 


let obj = { a: [{ foo: 123, bar: 'abc' }, {}], b: true }; 
let { a: [{foo: f}] } = obj; // f = 123 


11.3.1 Pick what you need 

If you destructure an object, you mention only those properties that you are interested in: 

let { x: x } = { x: 7, y: 3 }3 // x = 7 

If you destructure an Array, you can choose to only extract a prefix: 

let [x,y] = ['a', 'b', 'c']; // x='a'; y='b'; 

11.4 How do patterns access the innards of values? 

In an assignment pattern = someValue, how does the pattern access what’s inside someValue? 


11.4.1 Object patterns coerce values to objects 


The object pattern coerces destructuring sources to objects before accessing properties. That means 
that it works with primitive values: 
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let {length : len} = 'abc'; // len = 3 
let {toString: s} = 123; // s = Number.prototype. toString 


11.4.1.1 Failing to object-destructure a value 


The coercion to object is not performed via Object (), but via the internal operation ToObject()’. 
Object() never fails: 


> typeof Object('abc') 


‘object! 

> var obj = {}; 

> Object(obj) === obj 
true 

> Object (undefined) 
{} 

> Object (null) 

{} 


ToObject() throws a TypeError if it encounters undefined or null. Therefore, the following 
destructurings fail, even before destructuring accesses any properties: 


let { prop: x } = undefined; // TypeError 
let { prop: y } = null; // TypeError 


As a consequence, you can use the empty object pattern {} to check whether a value is coercible to 
an object. As we have seen, only undefined and null aren't: 


({} = [true, false]); // OK, Arrays are coercible to objects 
(1) = 'abc'); // OK, strings are coercible to objects 


({} = undefined); // TypeError 
({} = null); // TypeError 


The parentheses around the expressions are necessary because statements must not begin with curly 
braces in JavaScript. 


11.4.2 Array patterns work with iterables 


Array destructuring uses an iterator to get to the elements of a source. Therefore, you can Array- 
destructure any value that is iterable. Let’s look at examples of iterable values. 


Strings are iterable: 


*http://www.ecma-international.org/ecma-262/6.0/#sec-toobject 
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let [x,...y] = 'abc'; // x='a'; y=['b', 'c'] 


Don't forget that the iterator over strings returns code points (“Unicode characters”, 21 bits), not 
code units (“JavaScript characters”, 16 bits). (For more information on Unicode, consult the chapter 
“Chapter 24. Unicode and JavaScript?” in “Speaking JavaScript”.) For example: 


let [x,y,z] = 'a\uD83D\uDCA9c'; // x='a'; y='\uD83D\uDCA9'; z='c' 


You can’t access the elements of a Set via indices, but you can do so via an iterator. Therefore, Array 
destructuring works for Sets: 


let [x,y] = new Set(['a', 'b']); // x='a'; y="b”; 


The Set iterator always returns elements in the order in which they were inserted, which is why 
the result of the previous destructuring is always the same. 


Infinite sequences. Destructuring also works for iterators over infinite sequences. The generator 
function allNaturalNumbers() returns an iterator that yields 0, 1, 2, etc. 


function» allNaturalNumbers() { 
for (let n = 0; ; n++) { 
yield n; 


The following destructuring extracts the first three elements of that infinite sequence. 
let [x, y, z] = allNaturalNumbers(); // x=0; y=1; z=2 


11.4.2.1 Failing to Array-destructure a value 


A value is iterable if it has a method whose key is Symbol. iterator that returns an object. Array- 
destructuring throws a TypeError if the value to be destructured isn’t iterable: 


?http://speakingjs.com/es5/ch24.html 
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let x; 
[x] = [true, false]; // OK, Arrays are iterable 
[x] = 'abc'; // OK, strings are iterable 


[x] = { * [Symbol.iterator]() { yield 1 } ); // OK, iterable 


[x] = {}; // TypeError, empty objects are not iterable 


[x] = undefined; // TypeError, not iterable 


[x] = null; // TypeError, not iterable 


The TypeError is thrown even before accessing elements of the iterable, which means that you can 
use the empty Array pattern [] to check whether a value is iterable: 


[] = {}; // TypeError, empty objects are not iterable 
[] = undefined; // TypeError, not iterable 
[] null; // TypeError, not iterable 


11.5 If a part has no match 


Similarly to how JavaScript handles non-existent properties and Array elements, destructuring fails 
silently if the target mentions a part that doesn’t exist in the source: the interior of the part is matched 
against undefined. If the interior is a variable that means that the variable is set to undefined: 


let [x] = []; // x = undefined 
let {prop:y} = {}; // y = undefined 


Remember that object patterns and Array patterns throw a TypeError if they are matched against 
undefined. 


11.5.1 Default values 


Default values are a feature of patterns: If a part (an object property or an Array element) has no 
match in the source, it is matched against: 


e its default value (if specified) 
e undefined (otherwise) 


That is, providing a default value is optional. 


Let's look at an example. In the following destructuring, the element at index 0 has no match on the 
right-hand side. Therefore, destructuring continues by matching x against 3, which leads to x being 
set to 3. 
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let [x=3, y] = []; // x = 3; y = undefined 

You can also use default values in object patterns: 

let (foo: x=3, bar: y} = {}; // x = 3; y = undefined 


11.5.1.1 undefined triggers default values 


Default values are also used if a part does have a match and that match is undefined: 


let [x=1] = [undefined]; // x = 1 
let (prop: y=2} = {prop: undefined}; // y = 2 


The rationale for this behavior is explained in the next chapter, in the section on parameter default 
values. 


11.5.1.2 Default values are computed on demand 


The default values themselves are only computed when they are needed. In other words, this 
destructuring: 
let (prop: y=someFunc()} = someValue; 


is equivalent to: 


let y; 

if (someValue.prop === undefined) { 
y = someFunc() ; 

} else { 
y = someValue.prop; 


You can observe that if you use console.log(): 
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> function log(x) { console.log(x); return 'YES' } 


> let [a=log('hello')] 
hello 

> a 

"YES" 


11; 


> let [b=log('hello')] = [123]; 
> b 
123 


In the second destructuring, the default value is not triggered and log() is not called. 


11.5.1.3 Default values can refer to other variables in the pattern 


A default value can refer to any variable, including another variable in the same pattern: 
let [x=3, y=x] = []; // x=3;3 y=3 
let [x=3, y=x] = [7]; A yT 


tet [x=3; y=x] = [T; 215 77 3873 y=2 


However, order matters: the variables x and y are declared from left to right and produce a 
ReferenceError if they are accessed before their declaration: 


let [x=y, y=3] = []; // ReferenceError 


11.5.1.4 Default values for patterns 


So far we have only seen default values for variables, but you can also associate them with patterns: 
let [{ prop: x } = {}] = []; 
What does this mean? Recall the rule for default values: 


If the part has no match in the source, destructuring continues with the default value 


[... 


The element at index 0 has no match, which is why destructuring continues with: 
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let { prop: x } = {}3 // x = undefined 


You can more easily see why things work this way if you replace the pattern { prop: x } with 
the variable pattern: 


let [pattern = {}] = []; 


More complex default values. Let’s further explore default values for patterns. In the following 
example, we assign a value to x via the default value { prop: 123 }: 


let [{ prop: x } = { prop: 123 }] = [13 


Because the Array element at index 0 has no match on the right-hand side, destructuring continues 
as follows and x is set to 123. 


let { prop: x } = { prop: 123 }; // x = 123 


However, x is not assigned a value in this manner if the right-hand side has an element at index 0, 
because then the default value isn’t triggered. 


let [{ prop: x } = { prop: 123 }] = [47]; 
In this case, destructuring continues with: 
let { prop: x } = {}3 // x = undefined 


Thus, if you want x to be 123 if either the object or the property is missing, you need to specify a 
default value for x itself: 


let [{ prop: x=123 } = {}] = [{}]; 


Here, destructuring continues as follows, independently of whether the right-hand side is [{}] or 


Lil 
let { prop: x=123 } = {}; // x = 123 


Still confused? 


A later section explains destructuring from a different angle, as an algorithm. That may 
give you additional insight. 
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11.6 More object destructuring features 


11.6.1 Property value shorthands 

Property value shorthands are a feature of object literals: If the value of a property is provided via 
a variable whose name is the same as the key, you can omit the key. This works for destructuring, 
too: 

let { x, y } = { x: 11, y: 8 }; // x= 11; y = 8 

This declaration is equivalent to: 

let { x: x, y: y } = { x: 11, y: 8 9; 

You can also combine property value shorthands with default values: 

let { x, y= 1 } = {33 // x = undefined; y = 1 

11.6.2 Computed property keys 


Computed property keys are another object literal feature that also works for destructuring: You can 
specify the key of a property via an expression, if you put it in square brackets: 


const FOO = 'foo'; 
let { [FOO]: f } = £ foo: 123 }3 // f = 123 


Computed property keys allow you to destructure properties whose keys are symbols: 
// Create and destructure a property whose key is a symbol 

const KEY = Symbol() ; 

let obj = { [KEY]: 'abc' }; 

let { [KEY]: x } = obj; // x = 'abc' 

// Extract Array.prototype[Symbol.iterator ] 


let { [Symbol.iterator]: func } = []; 
console. log(typeof func); // function 


11.7 More Array destructuring features 


11.7.1 Elision 


Elision lets you use the syntax of Array “holes” to skip elements during destructuring: 
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11.7.2 Rest operator (.. .) 


The rest operator lets you extract the remaining elements of an Array into an Array. You can only 
use the operator as the last part inside an Array pattern: 


let [x, ...y] = ['a', 'b', 'c']3 // x='a'; y=['b', 'c'] 


The rest operator operator extracts data. The same syntax (...) is used by the spread 
operator, which contributes data to Array literals and function calls and is explained in the 
next chapter. 


If the operator can't find any elements, it matches its operand against the empty Array. That is, it 
never produces undefined or null. For example: 


let [x, y, ...z] = ['a']; // x='a'; y=undefined; z=[] 
The operand of the rest operator doesn't have to be a variable, you can use patterns, too: 


Vet. [X, ...[y, 21] = ['a', 'b', 'c']; 
// x = Vas y= Ups z= 'c! 


The rest operator triggers the following destructuring: 


[ys z] = ['b', 'c'] 


The spread operator (. . .) looks exactly like the rest operator, but it is used inside function 
calls and Array literals (not inside destructuring patterns). 


11.8 You can assign to more than just variables 


If you assign via destructuring, each assignment target can be everything that is allowed on the left- 
hand side of a normal assignment, including a reference to a property (obj . prop) and a reference 
to an Array element (arr[0]). 
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let obj = (7; 
let arr = []; 


({ foo: obj.prop, bar: arr[0] }) = { foo: 123, bar: true }; 


console. log(obj); // {prop:123} 
console. log(arr); // [true] 


You can also assign to object properties and Array elements via the rest operator (. . .): 
let obj = (7; 
[first, ...obj.rest] = ['a', 'b', 'c']; 


// first = 'a'; obj.rest = ['b', 'c'] 


If you declare variables or define parameters via destructuring then you must use simple identifiers, 
you can’t refer to object properties and Array elements. 


11.9 Pitfalls of destructuring 


There are two things to be mindful of when using destructuring: 


e You can’t start a statement with a curly brace. 
e During destructuring, you can either declare variables or assign to them, but not both. 


The next two sections have the details. 


11.9.1 Don't start a statement with a curly brace 


Because code blocks begin with a curly brace, statements must not begin with one. This is 
unfortunate when using object destructuring in an assignment: 


{ a, b } = someObject; // SyntaxError 
The work-around is to put the complete expression in parentheses: 
({ a, b } = someObject); // ok 


11.9.2 You can’t mix declaring and assigning to existing variables 


Within a destructuring variable declaration, every variable in the source is declared. In the following 
example, we are trying to declare the variable b and refer to the existing variable f, which doesn’t 
work. 
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let f; 
let { foo: f, bar: b } = someObject; 


// During parsing (before running the code): 
// SyntaxError: Duplicate declaration, f 


The fix is to use a destructuring assignment and to declare b beforehand: 
let f; 


let b; 
({ foo: f, bar: b }) = someObject; 


11.10 Examples of destructuring 


Let’s start with a few smaller examples. 


The for-of loop supports destructuring: 


let map = new Map().set(false, 'no').set(true, 'yes'); 
for (let [key, value] of map) { 
console. log(key + ' is ' + value); 


} 


You can use destructuring to swap values. That is something that engines could optimize, so that no 
Array would be created. 


[a, b] = [b, a]; 
You can use destructuring to split an Array: 


let [first, ...rest] = ['a', 'b', 'c']; 
// first = 'a'; rest = ['b', 'c'] 


11.10.1 Destructuring return values 


Some built-in JavaScript operations return Arrays. Destructuring helps with processing them: 
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let [all, year, month, day] = 
/*(\d\d\d\d)-(\d\d)-(\d\d) $/ 
.exec('2999-12-31'); 


If you are only interested in the groups (and not in the complete match, a11), you can use elision to 
skip the array element at index 0: 


let [, year, month, day] = 
/*(\d\d\d\d)-(\d\d)-(\d\d) $/ 
.exec('2999-12-31'); 


exec () returns null if the regular expression doesn't match. Unfortunately, you can’t handle null 
via default values, which is why you must use the Or operator (| |) in this case: 


let [, year, month, day] = 
/*(\d\d\d\d)-(\d\d)-(\d\d) $/ 


.exec(someStr) || []; 


11.10.2 Multiple return values 


To see the usefulness of multiple return values, let's implement a function findElement (a, p) that 
searches for the first element in the Array a for which the function p returns true. The question is: 
what should that function return? Sometimes one is interested in the element itself, sometimes in 
its index, sometimes in both. The following implementation returns both. 


function findElement (array, predicate) { 
for (let [index, element] of array.entries()) 4 // (A) 
if (predicate(element)) { 
return { element, index }; // (B) 


} 


return { element: undefined, index: -1 }; 


In line A, the Array method entries() returns an iterable over [index,element] pairs. We 
destructure one pair per iteration. In line B, we use property value shorthands to return the object 
{ element: element, index: index }. 


Let’s use findElement(). In the following example, several ECMAScript 6 features allow us to 
write more concise code: The callback is an arrow function, the return value is destructured via an 
object pattern with property value shorthands. 
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let arr = [7, 8, 6]; 
let (element, index} = findElement(arr, x => x % 2 === 0); 
// element = 8, index = 1 


Due to index and element also referring to property keys, the order in which we mention them 
doesn’t matter: 


let {index, element} = findElement(::-); 

We have successfully handled the case of needing both index and element. What if we are only 
interested in one of them? It turns out that, thanks to ECMAScript 6, our implementation can take 
care of that, too. And the syntactic overhead compared to functions with single return values is 
minimal. 


let a = [7, 8, 6]; 


let {element} = findElement(a, x => x % 2 === 0); 
// element = 8 


let {index} = findElement(a, x => x % 2 === 0); 
// index = 1 


Each time, we only extract the value of the one property that we need. 


11.11 The destructuring algorithm 


This section looks at destructuring from a different angle: as a recursive pattern matching algorithm. 


O This different angle should especially help with understanding default values. If you feel 
you don't fully understand them yet, read on. 


At the end, Pll use the algorithm to explain the difference between the following two function 
declarations. 


function move({x=0, y=0 
function move({x, y} = 


= {}) LAS 


} 
{ x: 0, y: 073) 4 +++ } 


11.11.1 The algorithm 


A destructuring assignment looks like this: 
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«pattern» = «value» 


We want to use pattern to extract data from value. I'll now describe an algorithm for doing so, 
which is known in functional programming as pattern matching (short: matching). The algorithm 
specifies the operator < (“match against”) for destructuring assignment that matches a pattern 
against a value and assigns to variables while doing so: 


«pattern» < «value» 


The algorithm is specified via recursive rules that take apart both operands of the < operator. The 
declarative notation may take some getting used to, but it makes the specification of the algorithm 
more concise. Each rule has two parts: 


e The head specifies which operands are handled by the rule. 
e The body specifies what to do next. 


I only show the algorithm for destructuring assignment. Destructuring variable declarations and 
destructuring parameter definitions work similarly. 


I don’t cover advanced features (computed property keys; property value shorthands; object 
properties and array elements as assignment targets), either. Only the basics. 


11.11.1.1 Patterns 


A pattern is either: 


e A variable: x 
e An object pattern: («properties») 
e An Array pattern: [«elements»] 


Each of the following sections describes one of these three cases. 


11.11.1.2 Variable 
e (1)x < value (including undefined and null) 


x = value 


11.11.1.3 Object pattern 


a (2a) {«properties»} < undefined 
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throw new TypeError(); 
e (2b) («properties») < null 
throw new TypeError(); 
e (2c) (key: «pattern», «properties»} < obj 


«pattern» < obj.key 
{«properties»} < obj 


e (2d) (key: «pattern» = default_value, «properties»} < obj 


let tmp = obj.key; 


if (tmp !== undefined) { 
«pattern» < tmp 
} else Y 


«pattern» < default_value 
} 


{«properties»} < obj 


e (2e) {} € obj 


// No properties left, nothing to do 


11.11.1.4 Array pattern 


Array pattern and iterable. The algorithm for Array destructuring starts with an Array pattern 
and an iterable: 


e (3a) [«elements»] < non_iterable 
assert(!isIterable(non_iterable) ) 


throw new TypeError() ; 


e (3b) [«elements»] < iterable 
assert(isIterable(iterable) ) 


let iterator = iterable[Symbol.iterator] (); 
«elements» < iterator 


Helper function: 
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function isIterable(value) { 


return (value !== null 
&& typeof value === 'object' 
&& typeof value[Symbol.iterator] === 'function'); 


Array elements and iterator. The algorithm continues with the elements of the pattern and an 
iterator (obtained from the iterable). 


e (3c) «pattern», «elements» € iterator 


«pattern» < getNext(iterator) // undefined after last item 
«elements» < iterator 


e (3d) «pattern» = default_value, «elements» < iterator 


let tmp = getNext(iterator); // undefined after last item 


if (tmp !== undefined) { 
«pattern» < tmp 
j else { 


«pattern» < default_value 


} 


«elements» < iterator 


e (3e), «elements» + iterator (hole, elision) 


getNext(iterator); // skip 
«elements» < iterator 


e (3f) ... «pattern» < iterator (always last part!) 


let tmp = []; 

for (let elem of iterator) { 
tmp.push(elem); 

} 


«pattern» < tmp 


e (3g)< iterator 


// No elements left, nothing to do 


Helper function: 
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function getNext(iterator) { 
let {done,value} = iterator.next(); 
return (done ? undefined : value); 


11.11.2 Applying the algorithm 


The following function definition has named parameters, a technique that is sometimes called 
options object and explained in the chapter on parameter handling. The parameters use destructuring 
and default values in such a way that x and y can be omitted. But the object with the parameter can 
be omitted, too, as you can see in the last line of the code below. This feature is enabled via the = 
{} in the head of the function definition. 


function movel({x=0, y=0} = {}) { 
return [x, y]; 

} 

movel({x: 3, y: 8}); // [3, 8] 

movel({x: 33); // [3, 0] 

movel({}); // [0, 0] 

move1(); // [0, 0] 


But why would you define the parameters as in the previous code snippet? Why not as follows — 
which is also completely legal ES6 code? 


function move2({x, y) = { x: 0, y: © }) { 
return [x, y]; 


} 


To see why move1() is correct, let's use both functions for two examples. Before we do that, let's 
see how the passing of parameters can be explained via matching. 


11.11.2.1 Background: passing parameters via matching 


For function calls, formal parameters (inside function definitions) are matched against actual 
parameters (inside function calls). As an example, take the following function definition and the 
following function call. 


function func(a=0, b=0) { +++ } 
func(1, 2); 


The parameters a and b are set up similarly to the following destructuring. 
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[a=0, b=0] € [1, 2] 


11.11.2.2 Using move2() 


Let's examine how destructuring works for move2(). 


Example 1. move2() leads to this destructuring: 
[{x, y} = { x: 0, y: 0 }] < [] 
The only Array element on the left-hand side does not have a match on the right-hand side, which 


is why {x,y} is matched against the default value and not against data from the right-hand side 
(rules 3b, 3d): 


lx, y} e { x: 0, y: 0} 

The left-hand side contains property value shorthands, it is an abbreviation for: 
{x: x, y: y} e { x: 0, y: 0 } 

This destructuring leads to the following two assignments (rule 2c, 1): 


x = 05 
y = 0; 


However, this is the only case in which the default value is used. 


Example 2. Let’s examine the function call move2 ({z:3}) which leads to the following destructur- 
ing: 


Lix, y} = { x: 0, y: © }] < [42:37] 


There is an Array element at index 0 on the right-hand side. Therefore, the default value is ignored 
and the next step is (rule 3d): 


{x, y} e { z: 3} 
That leads to both x and y being set to undefined, which is not what we want. 


11.11.2.3 Using move1() 


Let’s try move1(). 


Example 1: move1() 
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[{x=0, y=0} = {}] < [] 


We don’t have an Array element at index 0 on the right-hand side and use the default value (rule 
3d): 


{x=0, y=0} < {} 


The left-hand side contains property value shorthands, which means that this destructuring is 
equivalent to: 


{x: x=0, y: y=0} < {} 


Neither property x nor property y have a match on the right-hand side. Therefore, the default values 
are used and the following destructurings are performed next (rule 2d): 


x € 0 
yen 


That leads to the following assignments (rule 1): 


x= 0 
y= 0 


Example 2: movel({z:3}) 
[{x=0, y=0} = {}] € [{z:3}] 


The first element of the Array pattern has a match on the right-hand side and that match is used to 
continue destructuring (rule 3d): 


{x=0, y=0} < {z:3} 


Like in example 1, there are no properties x and y on the right-hand side and the default values are 
used: 


11.11.3 Conclusion 


The examples demonstrate that default values are a feature of pattern parts (object properties or 
Array elements). If a part has no match or is matched against undefined then the default value is 
used. That is, the pattern is matched against the default value, instead. 


12. Parameter handling 


Parameter handling has been significantly upgraded in ECMAScript 6. It now supports parameter 
default values, rest parameters (varargs) and destructuring. 


O For this chapter, it is useful to be familiar with destructuring (which is explained in the 
previous chapter). 


12.1 Overview 


Default parameter values: 


function findClosestShape(x=0, y=0) { 
EP teas 


Rest parameters: 


function format(pattern, ...params) { 
return params; 


} 
console.log(format('a', 'b', 'c')); // ['b', 'c'] 


Named parameters via destructuring: 
function selectEntries({ start=0, end=-1, step=1 } = {}) £ 
// The object pattern is an abbreviation of: 


// { start: start=0, end: end=-1, step: step=1 } 


// Use the variables ‘start’, ‘end’ and 'step' here 


selectEntries({ start: 10, end: 30, step: 2 }); 
selectEntries({ step: 3 }); 

selectEntries({}); 

selectEntries(); 
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12.1.1 Spread operator (...) 


In function and constructor calls, the spread operator turns iterable values into arguments: 


> Math.max(-1, 5, 11, 3) 


11 

> Math.max(...[-1, 5, 11, 3]) 

11 

> Math.max(-1, ...[-1, 5, 11], 3) 
11 


In Array literals, the spread operator turns iterable values into Array elements: 


> ell, dl 
[1, 2, 3, 4] 


12.2 Parameter handling as destructuring 


The ES6 way of handling parameters is equivalent to destructuring the actual parameters via the 
formal parameters. That is, the following function call: 


function func(«FORMAL_PARAMETERS») ( 
«CODE» 


} 
func(«ACTUAL_PARAMETERS») ; 


is roughly equivalent to: 


{ 
let [«FORMAL_PARAMETERS»] = [«ACTUAL_PARAMETERS» ] 5 
{ 
«CODE» 
t 
i; 


Example — the following function call: 
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function logSum(x=0, y=0) { 
console.log(x + y); 

} 

logSum(7, 8); 


becomes: 
{ 
let [x=0, y=0] = [7, 8]; 
{ 
console. log(x + y); 
} 


Let’s look at specific features next. 


12.3 Parameter default values 


ECMAScript 6 lets you specify default values for parameters: 


function f(x, y=0) { 
return [x, y]; 


} 


Omitting the second parameter triggers the default value: 


> f(1) 
[1, 0] 
> f() 
[undefined, 0] 


Watch out — undefined triggers the default value, too: 


> f(undefined, undefined) 
[undefined, 0] 


The default value is computed on demand, only when it is actually needed: 
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> const log = console.log.bind(console) ; 
> function g(x=log('x'), y=log('y')) {return 'DONE'} 
> 80 

x 

y 

"DONE ' 

> g(1) 

y 

"DONE ' 

> g(1, 2) 

"DONE' 


12.3.1 Why does undefined trigger default values? 


It isn’t immediately obvious why undefined should be interpreted as a missing parameter or a 
missing part of an object or Array. The rationale for doing so is that it enables you to delegate the 
definition of default values. Let’s look at two examples. 


In the first example (source: Rick Waldron’s TC39 meeting notes from 2012-07-24’), we don’t have 
to define a default value in setOptions(), we can delegate that task to setLevel (). 


function setLevel(newLevel = 0) ( 
light.intensity = newLevel; 

} 

function setOptions(options) { 
// Missing prop returns undefined => use default 
setLevel(options.dimmerLevel); 
setMotorSpeed(options.speed) ; 


} 
setOptions({speed:5}); 


In the second example, square () doesn't have to define a default for x, it can delegate that task to 
multiply(): 


*https://github.com/rwaldron/tc39-notes/blob/master/es6/2012-07/july-24.md#413-destructuring- issues 
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function multiply(x=1, y=1) { 
return x x y; 

} 

function square(x) { 
return multiply(x, x); 


} 


Default values further entrench the role of undefined as indicating that something doesn’t exist, 
versus null indicating emptiness. 


12.3.2 Referring to other parameters in default values 


Within a parameter default value, you can refer to any variable, including other parameters: 


function foo(x=3, y=x) 1 :** } 
foo(); // x=3; y=3 
foo(7); // x=73 y=7 
foo(7, 2); // x=73 y=2 


However, order matters: parameters are declared from left to right and within a default value, you 
get a ReferenceError if you access a parameter that hasn’t been declared, yet. 


12.3.3 Referring to “inner” variables in default values 


Default values exist in their own scope, which is between the “outer” scope surrounding the function 
and the “inner” scope of the function body. Therefore, you can’t access “inner” variables from the 
default values: 


let x = 'outer'; 
function foo(a = x) ( 
let x = 'inner'; 


console.log(a); // outer 


If there were no outer x in the previous example, the default value x would produce a ReferenceEr- 
ror (if triggered). 


This restriction is probably most surprising if default values are closures: 
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function bar(callback = () => QUX) { 
const QUX = 3; // can’t be accessed from default value 
callback() ; 

} 


bar(); // ReferenceError 


To see why that is the case, consider the following implementation of bar () which is roughly 
equivalent to the previous one: 


function bar(...args) { // (A) 
let [callback = () => QUX] = args; // (B) 
1 // (©) 
const QUX = 3; // can’t be accessed from default value 
callback(); 


} 


Within the scope started by the opening curly brace at the end of line A, you can only refer to 
variables that are declared either in that scope or in a scope surrounding it. Therefore, variables 
declared in the scope starting in line C are out of reach for the statement in line B. 


12.4 Rest parameters 


Putting the rest operator (...) in front of the last formal parameter means that it will receive all 
remaining actual parameters in an Array. 


function f(x, ...y) { 


f('a', up”; les [I x = tas y= Eb; rer | 
If there are no remaining parameters, the rest parameter will be set to the empty Array: 


f(); // x = undefined; y = [] 


The spread operator (. . .) looks exactly like the rest operator, but it is used inside function 
calls and Array literals (not inside destructuring patterns). 


12.4.1 No more arguments! 


Rest parameters can completely replace JavaScript’s infamous special variable arguments. They 
have the advantage of always being Arrays: 
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// ECMAScript 5: arguments 
function logAllArguments() { 
for (var i=0; i < arguments.length; i++) { 
console. log(arguments[i]) ; 


// ECMAScript 6: rest parameter 
function logAllArguments(...args) { 
for (let arg of args) { 
console. log(arg) ; 


12.4.1.1 Combining destructuring and access to the destructured value 


One interesting feature of arguments is that you can have normal parameters and an Array of all 
parameters at the same time: 


function foo(x=0, y=0) { 
console. log('Arity: 'targuments. length); 


You can avoid arguments in such cases if you combine a rest parameter with Array destructuring. 
The resulting code is longer, but more explicit: 


function foo(...args) { 
let [x=0, y=0] = args; 
console. log('Arity: 'targs. length) ; 


The same technique works for named parameters (options objects): 
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function bar(options = {}) { 
let { namedParaml, namedParam2 } = options; 


if ('extra' in options) ( 


12.4.1.2 arguments is iterable 


arguments is iterable’ in ECMAScript 6, which means that you can use for-of and the spread 
operator: 


> (function () { return typeof arguments[Symbol.iterator] }()) 
'function' 

> (function () { return Array. isArray([...arguments]) }()) 
true 


12.5 Simulating named parameters 


When calling a function (or method) in a programming language, you must map the actual 
parameters (specified by the caller) to the formal parameters (of a function definition). There are 
two common ways to do so: 


e Positional parameters are mapped by position. The first actual parameter is mapped to the 
first formal parameter, the second actual to the second formal, and so on. 

e Named parameters use names (labels) to perform the mapping. Names are associated with 
formal parameters in a function definition and label actual parameters in a function call. It 
does not matter in which order named parameters appear, as long as they are correctly labeled. 


Named parameters have two main benefits: they provide descriptions for arguments in function 
calls and they work well for optional parameters. Pll first explain the benefits and then show you 
how to simulate named parameters in JavaScript via object literals. 


12.5.1 Named Parameters as Descriptions 


As soon as a function has more than one parameter, you might get confused about what each 
parameter is used for. For example, let's say you have a function, selectEntries(), that returns 
entries from a database. Given the function call: 


*Iterables are explained in another chapter. 
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selectEntries(3, 20, 2); 


what do these two numbers mean? Python supports named parameters, and they make it easy to 
figure out what is going on: 


# Python syntax 
selectEntries(start=3, end=20, step=2) 


12.5.2 Optional Named Parameters 


Optional positional parameters work well only if they are omitted at the end. Anywhere else, you 
have to insert placeholders such as null so that the remaining parameters have correct positions. 


With optional named parameters, that is not an issue. You can easily omit any of them. Here are 
some examples: 


# Python syntax 
selectEntries(step=2) 
selectEntries(end=20, start=3) 
selectEntries() 


12.5.3 Simulating Named Parameters in JavaScript 
JavaScript does not have native support for named parameters like Python and many other 
languages. But there is a reasonably elegant simulation: name parameters via an object literal, passed 


as a single actual parameter. When you use this technique, an invocation of selectEntries() looks 
as follows: 


selectEntries({ start: 3, end: 20, step: 2 }); 
The function receives an object with the properties start, end, and step. You can omit any of them: 


selectEntries({ step: 2 }); 
selectEntries({ end: 20, start: 3 }); 
selectEntries(); 


In ECMAScript 5, you'd implement selectEntries() as follows: 
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function selectEntries(options) { 


options = options || (7; 

var start = options.start || 0; 
var end = options.end || -1; 
var step = options.step || 1; 


} 
In ECMAScript 6, you can use destructuring, which looks like this: 


function selectEntries({ start=0, end=-1, step=1 }) { 


J 


If you call selectEntries() with zero arguments, the destructuring fails, because you can't match 
an object pattern against undefined. That can be fixed via a default value. In the following code, 
the object pattern is matched against {} if there isn’t at least one argument. 


function selectEntries({ start=0, end=-1, step=1 } = {}) { 


} 


You can also combine positional parameters with named parameters. It is customary for the latter 
to come last: 


someFunc (posArgl, { namedArgl: 7, namedArg2: true }); 


In principle, JavaScript engines could optimize this pattern so that no intermediate object is created, 
because both the object literals at the call sites and the object patterns in the function definitions are 
static. 


O In JavaScript, the pattern for named parameters shown here is sometimes called options or 
option object (e.g., by the ¡Query documentation). 


12.6 Examples of destructuring in parameter handling 


12.6.1 Reminder: parentheses around single parameters of arrow 
functions 


In the following sections, I’ll occasionally use arrow functions. Hence, a quick reminder: If an arrow 
function has a single parameter and that parameter is an identifier, you can omit the parentheses 
around it. For example, there are no parentheses around x in the following REPL interaction: 
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> [1,2,3].map(x => 2 * x) 
[ 2, 4, 6 ] 


However, you do need parentheses whenever a single parameter is not just an identifier: 


> [[1,2], [3,4]].map(([a,b]) => a + b) 
[ 3, 7 ] 


> [1, undefined, 3].map((x='yes') => x) 
[ 1, 'yes', 3 ] 


More details are given in the chapter on arrow functions. 


12.6.2 forEach() and destructuring 


You will probably mostly use the for-of loop in ECMAScript 6, but the Array method forEach() 
also profits from destructuring. Or rather, its callback does. 


First example: destructuring the Arrays in an Array. 


let items = [ ['foo', 3], ['bar', 9] ]; 
items.forEach(([word, count]) => { 
console. lLog(word+!' '+count) ; 


});5 
Second example: destructuring the objects in an Array. 


let items = [ 
{ word:'foo', count:3 }, 
{ word:'bar', count:9 }, 

1; 

items.forEach(({word, count}) => { 
console.log(word+' '+count); 


}); 
12.6.3 Transforming Maps 
An ECMAScript 6 Map doesn’t have a method map () (like Arrays). Therefore, one has to: 


1. Convert it to an Array of [key,value] pairs. 
2. map() the Array. 
3. Convert the result back to a Map. 


This looks as follows. 
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let map0 = new Map([ 
Lis waay 
[2, 'b'], 
[3, te) 

1); 


let mapl = new Map( // step 3 
[...map0] // step 1 
.map(([k, v]) => [k*2, '_'+v]) // step 2 
); 
// Resulting Map: {2 -> '_a', 4 -> '_b', 6 -> '_c') 


12.6.4 Handling an Array returned via a Promise 


The tool method Promise.all() works as follows: 


e Input: an Array of Promises. 
e Output: a Promise that resolves to an Array as soon as the last input Promise is resolved. The 
Array contains the resolutions of the input Promises. 


Destructuring helps with handling the Array that the result of Promise.all() resolves to: 


let urls = [ 
'http://example.com/foo.html', 
'http://example.com/bar.html', 
"http: //example.com/baz.html', 
1; 


Promise.all(urls.map(downloadUrl)) 
.then(([fooStr, barStr, bazStr]) => ( 


$»; 
// This function returns a Promise that resolves to 
// a string (the text) 


function downloadUrl(url) { 
return fetch(url).then(request => request.text()); 


fetch() is a Promise-based version of XMLHttpRequest. It is part of the Fetch standard’. 


Shttps://fetch.spec.whatwg.org/#fetch-api 
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12.7 Coding style tips 


This section mentions a few tricks for descriptive parameter definitions. They are clever, but they 
also have downsides: they add visual clutter and can make your code harder to understand. 


12.7.1 Optional parameters 


I occasionally use the parameter default value undefined to mark a parameter as optional (unless 
it already has a default value): 


function foo(requiredParam, optionalParam = undefined) { 


} 


12.7.2 Required parameters 


In ECMAScript 5, you have a few options for ensuring that a required parameter has been provided, 
which are all quite clumsy: 


function foo(mustBeProvided) { 
if (arguments.length < 1) { 
throw new Error(); 
} 
if (! (0 in arguments)) { 
throw new Error(); 


} 
if (mustBeProvided === undefined) { 
throw new Error(); 


} 


In ECMAScript 6, you can (ab)use default parameter values to achieve more concise code (credit: 
idea by Allen Wirfs-Brock): 
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px 

x Called if a parameter is missing and 

* the default value is evaluated. 

*/ 

function mandatory() { 
throw new Error('Missing parameter'); 

} 

function foo(mustBeProvided = mandatory()) ( 
return mustBeProvided; 


Interaction: 


> foo() 

Error: Missing parameter 
> foo(123) 

123 


12.7.3 Enforcing a maximum arity 


This section presents three approaches to enforcing a maximum arity. The running example is a 
function f whose maximum arity is 2 — if a caller provides more than 2 parameters, an error should 
be thrown. 


The first approach collects all actual parameters in the formal rest parameter args and checks its 
length. 


function f(...args) { 
if (args.length > 2) £ 
throw new Error(); 


} 


// Extract the real parameters 
let [x, y] = args; 


The second approach relies on unwanted actual parameters appearing in the formal rest parameter 
empty. 
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function f(x, y, ...empty) { 
if (empty.length > 0) { 
throw new Error(); 


The third approach uses a sentinel value that is gone if there is a third parameter. One caveat is that 
the default value OK is also triggered if there is a third parameter whose value is undefined. 


const OK = Symbol(); 
function f(x, y, arity=0K) { 
if (arity !== OK) { 
throw new Error(); 


Sadly, each one of these approaches introduces significant visual and conceptual clutter. I’m tempted 
to recommend checking arguments. length, but I also want arguments to go away. 


function f(x, y) { 
if (arguments.length > 2) { 
throw new Error(); 


12.8 The spread operator (...) 
The spread operator (. . .) looks exactly like the rest operator, but is its opposite: 


e The rest operator extracts Arrays and is used for rest parameters and destructuring. 
e The spread operator turns the elements of an Array into arguments of a function call or into 
elements of an Array literal. 


12.8.1 Spreading into function and method calls 


Math.max() is a good example for demonstrating how the spread operator works in method calls. 
Math.max(x1, x2, +++) returns the argument whose value is greatest. It accepts an arbitrary 
number of arguments, but can’t be applied to Arrays. The spread operator fixes that: 
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> Math.max(-1, 5, 11, 3) 

11 

> Math.max(...[-1, 5, 11, 3]) 
EE 


In contrast to the rest operator, you can use the spread operator anywhere in a sequence of parts: 


> Math.max(-1, ...[-1, 5, 11], 3) 
11 


Another example is JavaScript not having a way to destructively append the elements of one Array 
to another one. However, Arrays do have the method push(x1, x2, +++), which appends all 
of its arguments to its receiver. The following code shows how you can use push() to append the 
elements of arr2 to arr1. 


let arr1 = [ 
let arr2 = [' 


arrl.push(...arr2); 
/f arri 1s now [ta*.. "Bry. Tet "at] 


12.8.2 Spreading into constructors 
In addition to function and method calls, the spread operator also works for constructor calls: 
new Date(...[1912, 11, 24]) // Christmas Eve 1912 


That is something that is difficult to achieve in ECMAScript 5*. 


12.8.3 Spreading into Arrays 


The spread operator can also be used inside Arrays: 


sy araa Al 
[1, 2, 3, 4] 


That gives you a convenient way to concatenate Arrays: 


“http://speakingjs.com/es5/ch17.html#apply_constructors 
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let x = ['a', 'b'] 
let y = ['c']; 
let z = dar, e]; 


let arr = [...x, ...y, .-.-Z]3 // ['a', 'b', 'c', "d"; 'e'] 


12.8.3.1 Converting iterable or Array-like objects to Arrays 


The spread operator lets you convert any iterable object to an Array: 
let arr = [...somelterable0bject]; 


Let's convert a Set to an Array: 


let set 
let arr 


new Set([11, -1, 6]); 
[...set]; // [11, -1, 6] 


Your own iterable objects can be converted to Arrays in the same manner: 


let obj = ( 
x [Symbol.iterator]() { 
yield 'a'; 
yield 'b'; 
yield 'c'; 
} 
}; 


let arr = [...obj]; // ['a', 'b', 'c'] 
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Note that, just like the for-of loop, the spread operator only works for iterable objects. Most 
important objects are iterable: Arrays, Maps, Sets and arguments. Most DOM data structures will 


also eventually be iterable. 


Should you ever encounter something that is not iterable, but Array-like (indexed elements plus a 


property length), you can use Array .from()* to convert it to an Array: 


‘Explained in the chapter on Arrays. 
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let arrayLike = £ 


nOr: Tar 
to tots 
a es 
length: 3 


}; 


// ECMAScript 5: 
var arrl = [].slice.call(arrayLike); // ['a', 'b', 'c'] 


// ECMAScript 6: 
let arr2 = Array.from(arrayLike); // ['a', 'b', 'c'] 


// TypeError: Cannot spread non-iterable object. 
let arr3 = [...arrayLike]; 


Ill Modularity 


13. Callable entities in ECMAScript 6 


This chapter gives advice on how to properly use entities you can call (via function calls, method 
calls, etc.) in ES6. It contains three sections: 


e An overview of callable entities. 

e Recommendations for what callable entity to use when. 

e An examination of two ways of calling methods and how they change with ES6: 
— Dispatched method calls, e.g. obj .m(x, y) 
— Direct method calls, e.g. obj .m.call(obj, x, y) 


13.1 Callable entities in ES6 


In ES6, there are the following callable entities: 


Traditional functions (created via function expressions and function declarations) 
Generator functions (created via generator function expressions and generator function 
declarations) 


e Arrow functions (only have an expression form) 

e Methods (created by method definitions in object literals and class definitions) 

e Generator methods (created by generator method definitions in object literals and class 
definitions) 

e Classes (created via class expressions and class declarations) 


Note that I distinguish: 


e The entity: e.g. traditional function 
e The syntax that creates the entity: e.g. function expression and function declaration 


Even though their behaviors differ considerably (as explained later), all of these entities are functions. 
For example: 
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> typeof (() => {}) // arrow function 


'function' 

> typeof function» () {} // generator function 
'function' 

> typeof class {} // class 

'function' 


Next, we look at each callable entity in more detail. 


13.1.1 Ways of calling in ES6 


Some calls can be made anywhere, others are restricted to specific locations. 


13.1.1.1 Calls that can be made anywhere 


Three kinds of calls can be made anywhere in ES6: 


e Function calls: func(3, 1) 
e Method calls: obj .method('abc') 
¢ Constructor calls: new Constr (8) 


For function calls, it is important to remember that most ES6 code will be contained in modules and 
that module bodies are implicitly in strict mode. 


13.1.1.2 Calls via super are restricted to specific locations 


Two kinds of calls can be made via the super keyword; their use is restricted to specific locations: 


e Super-method calls: super .method('abc') 
Only available within method definitions inside either object literals or derived class defini- 
tions. 

e Super-constructor calls: super (8) 
Only available inside the special method constructor () inside a derived class definition. 


13.1.1.3 Non-method functions versus methods 


The difference between non-method functions and methods is becoming more pronounced in 
ECMAScript 6. There are now special entities for both and things that only they can do: 


e Arrow functions are made for non-method functions. They pick up this (and other variables) 
from their surrounding scopes (“lexical this”). 

e Method definitions are made for methods. They provide support for super, to refer to super- 
properties and to make super-method calls. 
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13.1.2 Traditional functions 


These are the functions that you know from ES5. There are two ways to create them: 


e Function expression: 


const foo = function (x) { =: 7; 


¢ Function declaration: 


function foo(x) { =: } 
Rules for this: 


e Function calls: this is undefined in strict mode and the global object in sloppy mode. 
e Method calls: this is the receiver of the method call (or the first argument of call/apply). 
e Constructor calls: this is the newly created instance. 


13.1.3 Generator functions 


Generator functions are explained in the chapter on generators. Their syntax is similar to traditional 
functions, but they have an extra asterisk: 


e Generator function expression: 


const foo = functionx (x) { =: }3 


¢ Function declaration: 


function» foo(x) { =: } 
The rules for this are as follows. Note that it never refers to the generator object. 


¢ Function/method calls: this is handled like it is with traditional functions. The results of such 
calls are generator objects. 


e Constructor calls: Accessing this inside a generator function causes a ReferenceError. The 
result of a constructor call is a generator object. 


13.1.4 Method definitions 


Method definitions can appear inside object literals: 
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let obj = { 
add(x, y) { 
return x + y; 
3, // comma is required 


sub(x, y) { 
return x - y; 
}, // comma is optional 


Ja 
And inside class definitions: 


class AddSub { 


add(x, y) { 
return x + y; 
y // no comma 


sub(x, y) { 
return x - y; 
} // no comma 


As you can see, you must separate method definitions in an object literal with commas, but there 
are no separators between them in a class definition. The former is necessary to keep the syntax 
consistent, especially with regard to getters and setters. 


Method definitions are the only place where you can use super to refer to super-properties. Only 
method definitions that use super produce functions that have the property [[HomeObject]], 
which is required for that feature (details are explained in the chapter on classes). 


Rules: 


e Function calls: If you extract a method and call it as a function, it behaves like a traditional 
function. 


e Method calls: work as with traditional functions, but additionally allow you to use super. 
e Constructor calls: produce a TypeError. 


Inside class definitions, methods whose name is constructor are special, as explained later. 


13.1.5 Generator method definitions 


Generator methods are explained in the chapter on generators. Their syntax is similar to method 
definitions, but they have an extra asterisk: 


Callable entities in ECMAScript 6 


let obj = { 


x generatorMethod(:- 


Fs 
E 
class MyClass { 


x generatorMethod(:- 


Rules: 
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9 


9 


e Calling a generator method returns a generator object. 


e You can use this and super as you would in normal method definitions. 


13.1.6 Arrow functions 


Arrow functions are explained in their own chapter: 


let squares = [1,2,3].map(x => x * x); 


The following variables are lexical inside an arrow function (picked up from the surrounding scope): 


arguments 


super 
this 
new. target 


Rules: 


¢ Function calls: lexical this etc. 


e Method calls: You can use arrow functions as methods, but their this continues to be lexical 
and does not refer to the receiver of a method call. 


e Constructor calls: produce a TypeError. 


13.1.7 Classes 


Classes are explained in their own chapter. 
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// Base class: no ‘extends’ 
class Point { 
constructor(x, y) { 
this.x = x; 
this.y = y; 
} 
toString() { 
return `(${this.x}, ${this.y})`; 


// This class is derived from `Point` 
class ColorPoint extends Point { 
constructor (x, y, color) { 
super (x, y); 
this.color = color; 
} 
toString() { 
return super.toString() + ' in ' + this.color; 


The Method constructor is special, because it “becomes” the class. That is, classes are very similar 
to constructor functions: 


> Point.prototype.constructor === Point 
true 


Rules: 


e Function/method calls: Classes can't be called as functions or methods (why is explained in 
the chapter on classes). 


e Constructor calls: follow a protocol that supports subclassing. In a base class, an instance is 
created and this refers to it. A derived class receives its instance from its super-class, which 
is why it needs to call super before it can access this. 


13.2 Thoughts on style 


Here are a few recommendations for which callable entity to use when. 
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13.2.1 Prefer arrow functions as callbacks 


Whenever you can, you should use arrow functions as callbacks and not traditional factions. Arrow 
functions are more convenient, because you get lexical this and more compact syntax. 


13.2.1.1 Problem: this as an implicit parameter 


Alas, some JavaScript APIs use this as an implicit argument for their callbacks, which prevents you 
from using arrow functions. For example: The this in line B is an implicit argument of the function 
in line A. 


beforeEach(function () { // (A) 
this.addMatchers({ // (B) 
toBeInRange: function (start, end) { 


$»; 
}); 
This pattern is less explicit and prevents you from using arrow functions. 


13.2.1.2 Solution 1: change the API 


This is easy to fix, but requires the API to change: 


beforeEach(api => { 
api.addMatchers({ 
toBeInRange(start, end) { 


}); 
}); 


We have turned the API from an implicit parameter this into an explicit parameter api. I like this 
kind of explicitness. 


13.2.1.3 Solution 2: access the value of this in some other way 


In some APIs, there are alternate ways to get to the value of this. For example, the following code 
uses this. 
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var $button = $('#myButton'); 
$button.on('click', function () { 

this.classList.toggle('clicked'); 
$; 


But the target of the event can also be accessed via event. target: 


var Sbutton = $('fmyButton'); 
$button.on('click', event => { 

event.target.classList.toggle('clicked'); 
$»; 


13.2.2 Be careful with function declarations 


Function declarations are safe as non-method functions as long as you don't access this from them. 
(Should this be enforced by linters?) 


function foo(argl, arg2) ( 
} 


You also have the option of using const with an arrow function, which gives you lexical this, but 
— arguably — doesn’t look as nice: 


const foo = (argl, arg2) => { 
}; 
13.2.3 Prefer method definitions for methods 


Method definitions are the only way to create methods that use super. They are the obvious choice 
in object literals and classes (where they are the only way to define methods), but what about adding 
a method to an existing object? For example: 


MyClass.prototype.foo = function (argl, arg2) { 
}; 


The following is a quick (and somewhat dirty) way to do the same thing in ES6. 
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Object.assign(MyClass.prototype, { 
foo(argl, arg2) { 


} 
}); 


For more information and caveats, consult the section on Object.assign(). 


13.2.4 Methods versus callbacks 


There is a subtle difference between an object with methods and an object with callbacks. 


13.2.4.1 An object whose properties are methods 


The this of a method is the receiver of the method call (e.g. obj if the method call is obj.m(: + + )). 
For example, you can use the WHATWG streams API’ as follows: 


let surroundingObject = 4 
surroundingMethod() 4 
let obj = ( 
data: 'abc', 
start(controller) { 


console. log(this.data); // abc (x) 
this.pull(); // (**) 


}, 
pull() { 


}, 


cancel() { 


f; 
$; 
let stream = new ReadableStream(obj) ; 
3, 
ES 


That is, obj is an object whose properties start, pull and cancel are methods. Accordingly, these 
methods can use this to access object-local state (line *) and to call each other (line **). 


*https://streams.spec.whatwg.org/ 
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13.2.4.2 An object whose properties are callbacks 


The this of an arrow function is the this of the surrounding scope (lexical this). Arrow functions 
make great callbacks, because that is the behavior you normally want for callbacks (real, non-method 
functions). A callback shouldn't have its own this that shadows the this of the surrounding scope. 


If the properties start, pull and cancel are arrow functions then they pick up the this of 


surroundingMethod() (their surrounding scope): 


let surroundingObject = { 


}; 


surroundingData: 'xyz', 
surroundingMethod() { 
let obj = { 
start: controller => { 


console.log(this.surroundingData); // xyz (x) 
}s 
pull: () => { 
N Ssd 


cancel: () => { 


Fs 
35 
let stream = new ReadableStream(obj) ; 


}, 


let stream = new ReadableStream(); 


If the output in line * surprises you then consider the following code: 


let obj = ( 

foo: 123, 

bart) 4 
let f = () => console. log(this.foo); // 123 
let o= { 

p: () => console.log(this.foo), // 123 

$3 

}s 
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Inside method bar(), f and o.p work the same, because both arrow functions have the same 
surrounding lexical scope, bar (). The latter arrow function being surrounded by an object literal 
does not change that. 


13.2.5 Avoid IIFEs in ES6 


This section gives tips for avoiding IIFEs in ES6. 


13.2.5.1 Replace an IIFE with a block 


In ES5, you had to use an IIFE if you wanted to keep a variable local: 


(function () { // open IIFE 
var tmp = +++; 


FO); // close IIFE 


console.log(tmp); // ReferenceError 
In ECMAScript 6, you can simply use a block and a let declaration: 


{ // open block 
let tmp = +++; 


y) // close block 


console.log(tmp); // ReferenceError 


13.2.5.2 Replace an IIFE with a module 


In ECMAScript 5 code that doesn’t use modules via libraries (such as RequireJS, browserify or 
webpack), the revealing module pattern is popular, and based on an IIFE. Its advantage is that it 
clearly separates between what is public and what is private: 
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var my_module = (function () { 
// Module-private variable: 
var countInvocations = 0; 


function myFunc(x) { 
countInvocations++; 


// Exported by module: 
return ( 
myFunc: myFunc 
}; 
}0); 


This module pattern produces a global variable and is used as follows: 
my_module.myFunc(33) ; 

In ECMAScript 6, modules are built in, which is why the barrier to adopting them is low: 
// my_module.js 


// Module-private variable: 
let countInvocations = 0; 


export function myFunc(x) { 
countInvocations++; 


This module does not produce a global variable and is used as follows: 
import { myFunc } from 'my_module.js'; 
myFunc (33) ; 


13.2.5.3 Immediately-invoked arrow functions 


There is one use case where you still need an immediately-invoked function in ES6: Sometimes 
you only can produce a result via a sequence of statements, not via a single expression. If you 
want to inline those statements, you have to immediately invoke a function. In ES6, you can use 
immediately-invoked arrow functions if you want to: 
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const SENTENCE = 'How are you?'; 
const REVERSED_SENTENCE = (() => { 
// Iteration over the string gives us code points 
// (better for reversal than characters) 
let arr = [...SENTENCE]; 
arr.reverse(); 
return arr.join(''); 


DO; 


Note that you must parenthesize as shown (the parens are around the arrow function, not around 
the complete function call). Details are explained in the chapter on arrow functions. 


13.2.6 Use classes 


ES6 classes are not perfect and have their detractors. But I still recommend to use them, because 
there are also several objective arguments in their favor, as I explain in the chapter on classes. 


13.3 Dispatched and direct method calls in ECMAScript 
5 and 6 


There are two ways to call methods in JavaScript: 


e Via dispatch, e.g. obj .someMethod(arg0, argl) 
e Directly, e.g. someFunc.call(thisValue, arg0, argl) 


This section explains how these two work and why you will rarely call methods directly in 
ECMAScript 6. Before we get started, PII refresh your knowledge w.r.t. to prototype chains. 


13.3.1 Background: prototype chains 


Remember that each object in JavaScript is actually a chain of one or more objects. The first object 
inherits properties from the later objects. For example, the prototype chain of an Array ['a', 'b'] 
looks as follows: 


. The instance, holding the elements 'a' and 'b' 

. Array.prototype, the properties provided by the Array constructor 

. Object .prototype, the properties provided by the Object constructor 
. null (the end of the chain, so not really a member of it) 


A UO N FR 


You can examine the chain via Object.getPrototypeOf (): 
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> var arr = ['a', 'b']; 
> var p = Object.getPrototypeOf; 


> p(arr) === Array.prototype 
true 

> p(p(arr)) === Object.prototype 
true 


> p(p(p(arr))) 
null 


Properties in “earlier” objects override properties in “later” objects. For example, Array.prototype 
provides an Array-specific version of the toString() method, overriding Object. prototype. toString(). 


> var arr = ['a', 'b']; 
> Object. getOwnPropertyNames (Array.prototype) 


[ 'toString', 'join', 'pop', *** ] 
> arr.toString() 
'a,b' 


13.3.2 Dispatched method calls 


If you look at the method call arr.toString() you can see that it actually performs two steps: 


1. Dispatch: In the prototype chain of arr, retrieve the value of the first property whose name 
is toString. 

2. Call: Call the value and set the implicit parameter this to the receiver arr of the method 
invocation. 


You can make the two steps explicit by using the cal1() method of functions: 


> var func = arr.toString; // dispatch 
> func.call(arr) // direct call, providing a value for 'this' 
‘a,b! 


13.3.3 Direct method calls 
There are two ways to make direct method calls in JavaScript: 


e Function.prototype.call(thisValue, arg0?, argl?, ***) 
e Function.prototype.apply(thisValue, argArray) 
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Both method call and method apply are invoked on functions. They are different from normal 
function calls in that you specify a value for this. call provides the arguments of the method call 
via individual parameters, apply provides them via an Array. 


One problem of invoking a method via dynamic dispatch is that the method needs to be in the 
prototype chain of an object. cal1() enables you to call a method directly while specifying the 
receiver. That means that you can borrow a method from an object that is not in the current prototype 
chain. For example, you can borrow Object.prototype.toString and thus apply the original, 
un-overridden implementation of toString to arr: 


> Object.prototype.toString.call(arr) 
'[object Array]' 


Methods that work with a variety of objects (not just with instances of “their” constructor) are called 
generic. Speaking JavaScript has a list? of all methods that are generic. The list includes most Array 
methods and all methods of Object .prototype (which have to work with all objects and are thus 
implicitly generic). 


13.3.4 Use cases for direct method calls 


This section covers use cases for direct method calls. Each time, Pl first describe the use case in ES5 
and then how it changes with ES6 (where you'll rarely need direct method calls). 


13.3.4.1 ES5: Provide parameters to a method via an Array 


Some functions accept multiple values, but only one value per parameter. What if you want to pass 
the values via an Array? 


For example, push() lets you destructively append several values to an Array: 


var arr = ['a', 'b']; 
arr.push('c', 'd') 


mv Av v 


But you can’t destructively append a whole Array. You can work around that limitation by using 
apply (): 


*http://speakingjs.com/es5/ch17.html#list_of_generic_methods 
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> var arr = ['a', 'b']; 

> Array.prototype.push.apply(arr, ['c', 'd']) 
4 

> arr 


[ “ans PO Er, td! ] 
Similarly, Math.max() and Math.min() only work for single values: 


> Math.max(-1, 7, 2) 
7 


With apply (), you can use them for Arrays: 


> Math.max.apply(null, [-1, 7, 2]) 
7 


13.3.4.2 ES6: The spread operator (...) mostly replaces apply () 


Making a direct method call via apply () only because you want to turn an Array into arguments 
is clumsy, which is why ECMAScript 6 has the spread operator (...) for this. It provides this 
functionality even in dipatched method calls. 


> Math.max(...[-1, 7, 2]) 
7 


Another example: 


> let arr = ['a', 'b']; 

> arr.push(...['c', 'd']) 
4 

> arr 

[ "ary "D" ter td! ] 


As a bonus, spread also works with the new operator: 


> new Date(...[2011, 11, 24]) 
Sat Dec 24 2011 00:00:00 GMT+0100 (CET) 


Note that apply () can’t be used with new — the above feat can only be achieved via a complicated 
work-around’ in ECMAScript 5. 


*http://speakingjs.com/es5/ch17.html#apply_constructors 
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13.3.4.3 ES5: Convert an Array-like object to an Array 


Some objects in JavaScript are Array-like, they are almost Arrays, but don't have any of the Array 
methods. Let's look at two examples. 


First, the special variable arguments of functions is Array-like. It has a length and indexed access 
to elements. 


> var args = function () { return arguments }('a', 'b'); 
> args.length 

2 

> args[0] 

bat 


But arguments isn’t an instance of Array and does not have the method forEach(). 


> args instanceof Array 
false 

> args.forEach 
undefined 


Second, the DOM method document. querySelectorAll() returns an instance of NodeList. 


> document.querySelectorAll('a[href]') instanceof NodeList 

true 

> document.querySelectorAll('a[href]').forEach // no Array methods! 
undefined 


Thus, for many complex operations, you need to convert Array-like objects to Arrays first. That is 
achieved via Array.prototype.slice(). This method copies the elements of its receiver into a 
new Array: 


> var arr = ['a', 'b']; 
> arr.slice() 


[i tary rE” ] 
> arr.slice() === arr 
false 


If you call slice () directly, you can convert a NodeList to an Array: 
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var domLinks = document .querySelectorAll('a[href]'); 
var links = Array.prototype.slice.call(domLinks) ; 
links. forEach(function (link) { 

console. log(link) ; 
$; 


And you can convert arguments to an Array: 


function format(pattern) { 
// params start at arguments[1], skipping ‘pattern’ 
var params = Array.prototype.slice.call(arguments, 1); 
return params; 

} 

console.log(format('a', 'b', 'c')); // ['b', 'c'] 


13.3.4.4 ES6: Array-like objects are less burdensome 


On one hand, ECMAScript 6 has Array. from(), a simpler way of converting Array-like objects to 
Arrays: 


let domLinks = document.querySelectorAll('a[href]'); 
let Links = Array.from(domLinks) ; 
links. forEach(function (link) { 
console. log(link) ; 
$; 


On the other hand, you won't need the Array-like arguments, because ECMAScript 6 has rest 
parameters (declared via a triple dot): 


function format(pattern, ...params) { 
return params; 


} 
console. log(format('a', 'b', 'c')); // ['b', 'c'] 


13.3.4.5 ES5: Using hasOwnProperty() safely 


obj .hasOwnProperty ('prop' ) tells you whether obj has the own (non-inherited) property prop. 
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> var obj = { prop: 123 }; 


> obj .hasOwnProperty('prop') 
true 


> 'toString' in obj // inherited 

true 

> obj .hasOwnProperty('toString') // own 
false 


However, calling hasOwnProperty via dispatch can cease to work properly if Object. prototype. hasOwnProper: 
is overridden. 


> var obj1 = { hasOwnProperty: 123 }; 
> obj1.hasOwnProperty('toString') 
TypeError: Property 'hasOwnProperty' is not a function 


hasOwnProperty may also be unavailable via dispatch if Object.prototype is not in the 
prototype chain of an object. 


> var obj2 = Object.create(null) ; 
> obj2.hasOwnProperty('toString' ) 
TypeError: Object has no method 'hasOwnProperty' 


In both cases, the solution is to make a direct call to hasOwnProperty: 


> var obj1 = { hasOwnProperty: 123 }; 
> Object.prototype.hasOwnProperty.call(obj1, 'hasOwnProperty') 
true 


> var obj2 = Object.create(null) ; 
> Object.prototype.hasOwnProperty.call(obj2, 'toString' ) 
false 


13.3.4.6 ES6: Less need for hasOwnProperty() 


hasOwnProperty() is mostly used to implement Maps via objects. Thankfully, ECMAScript 6 has 
a built-in Map data structure, which means that you'll need hasOwnProperty () less. 


13.3.4.7 ES5: Avoiding intermediate objects 


Applying an Array method such as join() to a string normally involves two steps: 
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var str = 'abc'; 

var arr = str.split(''); // step 1 
var joined = arr.join('-'); // step 2 
console.log(joined); // a-b-c 


Strings are Array-like and can become the this value of generic Array methods. Therefore, a direct 
call lets you avoid step 1: 


var str = 'abc'; 
var joined = Array.prototype.join.call(str, '-'); 


Similarly, you can apply map() to a string either after you split it or via a direct method call: 


> function toUpper(x) { return x.toUpperCase() } 
> 'abc'.split('').map(toUpper) 
[i PAS ; 'B! 5 1 ] 


> Array.prototype.map.call('abc', toUpper) 
[ PA? ; B! š tE" ] 


Note that the direct calls may be more efficient, but they are also much less elegant. Be sure that 
they are really worth it! 


13.3.4.8 ES6: Avoiding intermediate objects 


Array .from() can convert and map in a single step, if you provide it with a callback as the second 
argument. 


> Array.from('abc', ch => ch.toUpperCase()) 
[ "A"; "BE, Le ] 


As a reminder, the two step solution is: 


> 'abc'.split('').map(function (x) { return x.toUpperCase() }) 
[ VAC "BY, "Cc! ] 


13.3.5 Abbreviations for Object .prototype and 
Array.prototype 


You can access the methods of Object .prototype via an empty object literal (whose prototype is 
Object.prototype). For example, the following two direct method calls are equivalent: 
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Object.prototype.hasOwnProperty.call(obj, 'propKey') 
{}.hasOwnProperty.call(obj, 'propKey') 


The same trick works for Array .prototype: 


Array.prototype.slice.call (arguments) 
[].slice.call (arguments) 


This pattern has become quite popular. It does not reflect the intention of the author as clearly as 
the longer version, but it’s much less verbose. Speed-wise*, there isn’t much of a difference between 
the two versions. 


‘http://jsperf.com/array-prototype-slice-call-vs-slice-call/17 


14. Arrow functions 


14.1 Overview 


There are two benefits to arrow functions. 


First, they are less verbose than traditional function expressions: 


let arr = [1, 2, 3]; 
let squares = arr.map(x => x * x); 


// Traditional function expression: 
let squares = arr.map(function (x) { return x * x }); 


Second, their this is picked up from surroundings (lexical). Therefore, you don’t need bind() or 
that = this, anymore. 


function UiComponent { 
let button = document.getElementById('myButton') ; 
button.addEventListener('click', () => { 
console. log('CLICK'); 
this.handleClick(); // lexical ‘this’ 
$; 


The following variables are all lexical: 


e arguments 
e super 

e this 

e new.target 


14.2 Traditional functions are bad non-method 
functions, due to this 


In JavaScript, traditional functions can be used as: 


190 
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1. Non-method functions 
2. Methods 
3. Constructors 


These roles clash: Due to roles 2 and 3, functions always have their own this. But that prevents you 
from accessing the this of, e.g., a surrounding method from inside a callback (role 1). 


You can see that in the following ES5 code: 


function Prefixer(prefix) { 
this.prefix = prefix; 
t 
Prefixer.prototype.prefixArray = function (arr) { // (A) 
‘use strict'; 
return arr.map(function (x) { // (B) 
// Doesn’t work: 
return this.prefix + x; // (C) 
$; 
$ 


In line C, we'd like to access this.name, but can’t do that because the this of the function from line 
B shadows the this of the method from line A. In strict mode, this is undefined in non-method 
functions, which is why we get an error if we use Prefixer: 


> var pre = new Prefixer('Hi '); 

> pre.prefixArray(['Joe', 'Alex']) 

TypeError: Cannot read property 'prefix' of undefined 
There are three ways to work around this problem in ECMAScript 5. 


14.2.1 Solution 1: that = this 


You can assign this to a variable that isn’t shadowed. That’s what’s done in line A, below: 
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function Prefixer(prefix) 4 
this.prefix = prefix; 
} 
Prefixer.prototype.prefixArray = function (arr) { 
var that = this; // (A) 
return arr.map(function (x) { 
return that.prefix + x; 
$; 
$5 


Now Prefixer works as expected: 


> var pre = new Prefixer('Hi '); 
> pre.prefixArray(['Joe', 'Alex']) 
[ 'Hi Joe', 'Hi Alex' ] 


14.2.2 Solution 2: specifying a value for this 


A few Array methods have an extra parameter for specifying the value that this should have when 
invoking the callback. That's the last parameter in line A, below. 


function Prefixer(prefix) 4 
this.prefix = prefix; 
} 
Prefixer.prototype.prefixArray = function (arr) { 
return arr.map(function (x) { 
return this.prefix + x; 
}, this); // (A) 
}; 


14.2.3 Solution 3: bind (this) 


You can use the method bind () to convert a function whose this is determined by how it is called 
(via call (), a function call, a method call, etc.) to a function whose this is always the same fixed 
value. That's what we are doing in line A, below. 
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function Prefixer(prefix) 4 
this.prefix = prefix; 
} 
Prefixer.prototype.prefixArray = function (arr) ( 
return arr.map(function (x) { 
return this.prefix + x; 
}.bind(this)); // (A) 
$5 


14.2.4 ECMAScript 6 solution: arrow functions 


Arrow functions are basically solution 3, with a more convenient syntax. With an arrow function, 
the code looks as follows. 


function Prefixer(prefix) { 
this.prefix = prefix; 
} 
Prefixer.prototype.prefixArray = function (arr) { 
return arr.map((x) => { 
return this.prefix + x; 
}); 
}; 


To fully ES6-ify the code, you'd use a class and a more compact variant of arrow functions: 


class Prefixer { 
constructor (prefix) { 
this.prefix = prefix; 
} 
prefixArray(arr) { 
return arr.map(x => this.prefix + x); // (A) 


In line A we save a few characters by tweaking two parts of the arrow function: 


e If there is only one parameter and that parameter is an identifier then the parentheses can be 
omitted. 
e An expression following the arrow leads to that expression being returned. 


In the code, you can also see that the methods constructor and prefixArray are defined using 
new, more compact ES6 syntax that also works in object literals. 
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14.3 Arrow function syntax 


The “fat” arrow => (as opposed to the thin arrow ->) was chosen to be compatible with CoffeeScript, 
whose fat arrow functions are very similar. 


Specifying parameters: 


O => 4 . } // no parameter 

x => { ... ) // one parameter, an identifier 
(x, y) => 1 . } // several parameters 
Specifying a body: 


=> [ return x x x y // block 


x 
x => x * x // expression, equivalent to previous line 


The statement block behaves like a normal function body. For example, you need return to give 
back a value. With an expression body, the expression is always implicitly returned. 


Note how much an arrow function with an expression body can reduce verbosity. Compare: 


let squares [1, 2, 3].map(function (x) { return x * x }); 
let squares = [1, 2, 3].map(x => x * x); 


14.4 Lexical variables 


14.4.1 Sources of variable values: static versus dynamic 


The following are two ways in which a variable can receive its value. 


First, statically (lexically): Its value is determined by the structure of the program, it receives its 
value from a surrounding scope. For example: 


let x = 123; 
function foo(y) { 


return x; // value received statically 


} 


Second, dynamically: It receives its value via a function call. For example: 
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function bar(arg) { 
return arg; // value received dynamically 


} 
14.4.2 Variables that are lexical in arrow functions 
The source of this is an important distinguishing aspect of arrow functions: 


e Traditional functions have a dynamic this, its value is determined by how they are called. 
e Arrow functions have a lexical this, its value is determined by the surrounding scope. 


The complete list’ of variables whose values are determined lexically is: 
e arguments 
e super 


e this 
e new.target 


14.5 Syntax pitfalls 


There are a few syntax-related details that can sometimes trip you up. 


14.5.1 Arrow functions bind very loosely 


Arrow functions bind very loosely. The reason is that you want every expression that can appear in 
an expression body to “stick together”, it should bind more tightly than the arrow function. 


As a consequence, you often have to wrap arrow functions in parentheses if they appear somewhere 
else. For example: 


console. lLog(typeof () => {}); // SyntaxError 
console. log(typeof (() => {})); // OK 


On the flip side, you can use typeof as an expression body without putting it in parens: 
const f = x => typeof x; 
14.5.2 Immediately-invoked arrow functions 


Remember Immediately Invoked Function Expressions (IIFEs)*? They look as follows and are used 
to simulate block-scoping and value-returning blocks in ECMAScript 5: 


*http://www.ecma-international.org/ecma-262/6.0/#sec-arrow-function- definitions-runtime-semantics- evaluation 
*http://speakingjs.com/es5/ch16.html#iife 
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(function () { // open IIFE 
// inside IIFE 
FO); // close IIFE 


You can save a few characters if you use an Immediately Invoked Arrow Function (IAF): 


(OQ => 1 
return 123 


HOS 


Similarly to IIFEs, you should terminate IIAFs with semicolons (or use an equivalent measure”), to 
avoid two consecutive IIAFs being interpreted as a function call (the first one as the function, the 
second one as the parameter). 


Even if the IAF has a block body, you must wrap it in parentheses, because it can't be (directly) 
function-called, due to how loosely it binds. Note that the parentheses must be around the arrow 
function. With IIFEs you have a choice: you can either put the parentheses around the whole 
statement or just around the function expression. 


As mentioned in the previous section, arrow functions binding loosely is useful for expression bodies, 
where you want this expression: 

const value = () => foo() 

to be interpreted as: 

const value = () => (foo()) 

and not as: 


const value = (() => foo)() 


A section in the chapter on callable entities has more information on using IIFEs and ILAFs in ES6. 


14.5.3 Omitting parentheses around single parameters 


Omitting the parentheses around the parameters is only possible if they consist of a single identifier: 


*http://speakingjs.com/es5/ch16.html#iife_prefix 
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> [1,2,3].map(x => 2 * x) 
[ 2, 4,6] 


As soon as there is anything else, you have to type the parentheses, even if there is only a single 
parameter. For example, you need parens if you destructure a single parameter: 


> [[1,2], [3,4]].map(([a,b]) => a + b) 
[25 7 J 


And you need parens if a single parameter has a default value (undefined triggers the default 
value!): 


> [1, undefined, 3].map((x='yes') => x) 
[ 1, 'yes', 3 ] 


14.5.4 You can’t use statements as expression bodies 


14.5.4.1 Expressions versus statements 


Quick review (consult “Speaking JavaScript” for more information’): 


Expressions produce (are evaluated to) values. Examples: 


3 + 4 
foo (7) 
‘abc'. Length 


Statements do things. Examples: 


while (true) { +++ } 
return 123; 


Most expressions’ can be used as statements, simply by mentioning them in statement positions: 


“http://speakingjs.com/es5/ch07.html#expr_vs_stmt 
The exceptions are function expressions and object literals, which you have to put in parentheses, because they look like function declarations 
and code blocks. 
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function bar() { 
3 + 4; 
foo(7); 
'abc'.length; 


14.5.4.2 The bodies of arrow functions 


If an expression is the body an arrow function, you don't need braces: 
asyncFunc.then(x => console.log(x)); 
However, statements have to be put in braces: 


asyncFunc.catch(x => { throw x }); 


14.5.5 Returning an object literal 


Having a block body in addition to an expression body means that if you want the expression body 
to be an object literal, you have to put it in parentheses. 


The body of this arrow function is a block with the label bar and the expression statement 123. 
let f = x => { bar: 123 } 
The body of this arrow function is an expression, an object literal: 


let f = x => ({ bar: 123 }) 


14.6 Arrow functions versus normal functions 
An arrow function is different from a normal function in only two ways: 


e The following constructs are lexical: arguments, super, this, new. target 

» It can’t be used as a constructor: There is no internal method [[Construct]] that allows a 
normal function to be invoked via new and no property prototype. Therefore, new (() => 
{}) throws an error. 


Apart from that, there are no observable differences between an arrow function and a normal 
function. For example, typeof and instanceof produce the same results: 
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> typeof () => {} 


‘function! 
> () => {} instanceof Function 
true 


> typeof function () {} 

"function! 

> function () {} instanceof Function 
true 


Consult the chapter on callable entities for more information on when to use arrow functions and 
when to use traditional functions. 


15. New OOP features besides classes 


Classes (which are explained in the next chapter) are the major new OOP feature in ECMAScript 6. 
However, it also includes new features for object literals and new utility methods in Object. This 


chapter describes them. 


15.1 Overview 


15.1.1 New object literal features 


Method definitions: 


let obj = { 
myMethod(x, y) { 


} 
}; 


Property value shorthands: 


let first = 'Jane'; 
let last = 'Doe'; 


let obj = { first, last }; 
// Same as: 


let obj = { first: first, last: 


Computed property keys: 


let propKey = 'foo'; 
let obj = £ 
[propKey]: true, 
['b'+'ar']: 123 
$; 


last }; 


This new syntax can also be used for method definitions: 


200 
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let obj = £ 
['h'+'ello']() { 
return 'hi'; 
} 
}; 
console.log(obj.hello()); // hi 


The main use case for computed property keys is to make it easy to use symbols as property keys. 


15.1.2 New methods in Object 


The most important new method of Object is assign(). Traditionally, this functionality was 
called extend() in the JavaScript world. In contrast to how this classic operation works, Ob- 
ject.assign() only considers own (non-inherited) properties. 


let obj = { foo: 123 }; 

Object.assign(obj, { bar: true }); 

console. log(JSON.stringify(obj)); 
// {"foo0":123,"bar":true} 


15.2 New features of object literals 


15.2.1 Method definitions 


In ECMAScript 5, methods are properties whose values are functions: 


var obj = £ 
myMethod: function (x, y) { 


} 
}; 


In ECMAScript 6, methods are still function-valued properties, but there is now a more compact 
way of defining them: 
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let obj = ( 
myMethod(x, y) { 


} 
}; 


Getters and setters continue to work as they did in ECMAScript 5 (note how syntactically similar 
they are to method definitions): 


let obj = £ 

get foo() { 
console.log('GET foo'); 
return 123; 

}s 

set bar(value) { 
console.log('SET bar to '+value); 
// return value is ignored 


$; 
Let's use obj: 


> obj.foo 

GET foo 

123 

> obj.bar = true 
SET bar to true 
true 


There is also a way to concisely define properties whose values are generator functions: 


let obj = { 
x myGeneratorMethod() { 


}; 


This code is equivalent to: 
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let obj = £ 
myGeneratorMethod: function» () { 


} 
}; 


15.2.2 Property value shorthands 


Property value shorthands let you abbreviate the definition of a property in an object literal: If the 
name of the variable that specifies the property value is also the property key then you can omit the 
key. This looks as follows. 


let x = 
let y = 
let obj 


, 


, 


Ie A 


{ x, y}; 

The last line is equivalent to: 

let obj = { x: x, y: y $; 

Property value shorthands work well together with destructuring: 


let obj = { x: 4, y: 1 }; 
let {x,y} = obj; 
console.log(x); // 4 
console. log(y); // 1 


One use case for property value shorthands are multiple return values (which are explained in the 
chapter on destructuring). 


15.2.3 Computed property keys 


Remember that there are two ways of specifying a key when you set a property. 


1. Via a fixed name: obj.foo = true; 
2. Via an expression: obj ['b'+'ar'] = 123; 


In object literals, you only have option #1 in ECMAScript 5. ECMAScript 6 additionally provides 
option #2: 
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let propKey = 'foo'; 
let obj = £ 
[propKey]: true, 
['b'+"ar']: 123 
$5 


This new syntax can also be used for method definitions: 


let obj = { 
Ln +"eltot | C). 4 
return 'hi'; 


}; 
console.log(obj.hello()); // hi 


The main use case for computed property keys are symbols: you can define a public symbol and use 
it as a special property key that is always unique. One prominent example is the symbol stored in 
Symbol. iterator. If on object has a method with that key, it becomes iterable: The method must 
return an iterator, which is used by constructs such as the for-of loop to iterate over the object. 
The following code demonstrates how that works. 


let obj = { 
x [Symbol.iterator]() { // (A) 
yield 'hello'; 
yield 'world'; 


$; 

for (let x of obj) { 
console. log(x) ; 

} 

// Output: 

// hello 

// world 


Line A starts a generator method definition with a computed key (the symbol stored in Sym- 
bol. iterator). 
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15. 


3 New methods of Object 


15.3.10bject.assign(target, source_1, source_2, 


e...) 


This method merges the sources into the target: It modifies target, first copies all enumerable own 
properties of source_1 into it, then all own properties of source_2, etc. At the end, it returns the 
target. 


let obj = { foo: 123 }; 
Object.assign(obj, { bar: true }); 
console. lLog(JSON.stringify (obj) ); 


Let’s 


// {"foo":123,"bar": true} 
look more close at how Object.assign() works: 


Both kinds of property keys: Obj ect .assign() supports both strings and symbols as property 
keys. 

Only enumerable own properties: Object.assign() ignores inherited properties and prop- 
erties that are not enumerable. 

Copying via assignment: Properties in the target object are created via assignment (internal 
operation [[Put]]). That means that if target has (own or inherited) setters, those will 
be invoked during copying. An alternative would have been to define new properties, 
an operation which always creates new own properties and never invokes setters. There 
originally was a proposal for a variant of Object.assign() that uses definition instead of 
assignment. That proposal has been rejected for ECMAScript 6, but may be reconsidered for 
later editions. 

You can’t move a method that uses super: Such a method has an internal property [ [Home- 
Object]] that ties it to the object it was created in. If you move it via Object. assign(), it 
will continue to refer to the super-properties of the original object. Details are explained in a 
section in the chapter on classes. 


15.3.1.1 Use cases for Object.assign() 


Let’s 


look at a few use cases. 


15.3.1.1.1 Adding properties to this You can use Object.assign() to add properties to this 
in a constructor: 
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class Point { 
constructor(x, y) { 
Object.assign(this, fx, y)); 


15.3.1.1.2 Providing default values for object properties Object.assign() is also useful for 
filling in defaults for missing properties. In the following example, we have an object DEFAULTS 
with default values for properties and an object options with data. 


const DEFAULTS = { 
logLevel: 0, 
outputFormat: 'html' 
35 
function processContent(options) ( 
options = Object.assign({}, DEFAULTS, options); // (A) 


In line A, we created a fresh object, copied the defaults into it and then copied options into it, 
overriding the defaults. Object.assign() returns the result of these operations, which we assign 
to options. 


15.3.1.1.3 Adding methods to objects Another use case is adding methods to objects: 


Object.assign(SomeClass.prototype, { 
someMethod(argl, arg2) { 


3, 
anotherMethod() { 


} 
Hp; 


You could also manually assign functions, but then you don’t have the nice method definition syntax 
and need to mention SomeClass .prototype each time: 


New OOP features besides classes 207 


SomeClass.prototype.someMethod = function (argl, arg2) ( 


E 
SomeClass.prototype.anotherMethod = function () { 


}; 


15.3.1.1.4 Cloning objects One last use case for Object.assign() is a quick way of cloning 
objects: 


function clone(orig) { 
return Object.assign({}, orig); 


This way of cloning is also somewhat dirty, because it doesn’t preserve the property attributes of 
orig. If that is what you need, you have to use property descriptors’. 


If you want the clone to have the same prototype as the original, you can use Object. getPrototypeOf () 
and Object.create(): 


function clone(orig) { 
let origProto = Object.getPrototype0f (orig); 
return Object.assign(Object.create(origProto), orig); 


15.3.2 Object. getOwnPropertySymbols (obj) 


Object. getOwnPropertySymbols (obj) retrieves all own’ symbol-valued property keys of obj. 
It complements Object .getOwnProper tyNames (), which retrieves all string-valued own property 
keys. Consult a later section for more details on iterating over property keys. 


15.3.3 Object.is(value1, value2) 


The strict equals operator (===) treats two values differently than one might expect. 


First, NaN is not equal to itself. 


*http://speakingjs.com/es5/ch17.html#property_attributes 
The own properties of an object are those that aren't inherited via its prototype chain. 
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> NaN === NaN 
false 


That is unfortunate, because it often prevents us from detecting NaN: 


> [0,NaN,2].indexOf (NaN) 
=i 


Second, JavaScript has two zeros’, but strict equals treats them as if they were the same value: 


> -0 === +0 
true 


Doing this is normally a good thing. 


Object.is() provides a way of comparing values that is a bit more precise than ===. It works as 
follows: 


> Object.is(NaN, NaN) 
true 

> Object.is(-0, +0) 
false 


Everything else is compared as with ===. 


15.3.3.1 Using Object.is() to find Array elements 


If we combine Object.is() with the new ES6 Array method findIndex(), we can find NaN in 
Arrays: 


function myIndexOf(arr, elem) { 
return arr. findIndex(x => Object.is(x, elem)); 


myIndex0f([0,NaN,2], NaN); // 1 


In contrast, indexOf() does not handle NaN well: 


*http://speakingjs.com/es5/ch11.html#two_zeros 
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> [0,NaN,2].indexOf (NaN) 
=L 


15.3.4 Object.setPrototypeOf (obj, proto) 


This method sets the prototype of obj to proto. The non-standard way of doing so in ECMAScript 
5, that is supported by many engines, is via assigning to the special property __proto__. The 
recommended way of setting the prototype remains the same as in ECMAScript 5: during the 
creation of an object, via Object.create(). That will always be faster than first creating an object 
and then setting its prototype. Obviously, it doesn't work if you want to change the prototype of an 
existing object. 


15.4 Iterating over property keys in ES6 


In ECMAScript 6, the key of a property can be either a string or a symbol. There are now five tool 
methods that retrieve the property keys of an object obj: 


+ Object.keys(obj) : Array<string> 
retrieves all string-valued keys of all enumerable own (non-inherited) properties. 
e Object.getOwnPropertyNames(obj) : Array<string> 
retrieves all string-valued keys of all own properties. 
e Object.getOwnPropertySymbols(obj) : Array<symbol> 
retrieves all symbol-valued keys of all own properties. 
e Reflect.ownKeys(obj) : Array<string|symbol> 
retrieves all keys of all own properties. 
e Reflect.enumerate(obj) : Iterator 
retrieves all string-valued keys of all enumerable properties. 


15.4.1 Iteration order of property keys 


All methods that iterate over property keys do so in the same order: 


e First all Array indices, sorted numerically. 
e Then all string keys (that are not indices), in the order in which they were created. 
e Then all symbols, in the order in which they were created. 


Note that the language specification defines an index as a string key that, when converted to an 
unsigned integer and back, is still the same string (it must also be smaller than 2°’-1, so that there is 
room for the length of an Array). That means that the spec views Array indices as string keys and 
that even normal objects can have Array indices: 
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> Reflect.ownKeys(f [Symbol()]:0, b:0, 10:0, 2:0, a:0 }) 
['2', '10', 'b', 'a', Symbol()] 


O Why does the spec standardize in which order 
property keys are returned? 
Answer by Tab Atkins Jr.*: 


Because, for objects at least, all implementations used approximately the same order 
(matching the current spec), and lots of code was inadvertently written that depended on 
that ordering, and would break if you enumerated it in a different order. Since browsers 
have to implement this particular ordering to be web-compatible, it was specced as a 
requirement. 


There was some discussion about breaking from this in Maps/Sets, but doing so would 
require us to specify an order that is impossible for code to depend on; in other words, 
we'd have to mandate that the ordering be random, not just unspecified. This was deemed 
too much effort, and creation-order is reasonable valuable (see OrderedDict in Python, for 
example), so it was decided to have Maps and Sets match Objects. 


re sl Two parts of the spec are relevant for this section: 
+t 


+ The section on Array exotic objects? has a note on what Array indices are. 
+ The section on the internal method [[OwnPropertyKeys]]* defines the order in 
which properties are returned. 


15.5 FAQ: object literals 


15.5.1 Can | use super in object literals? 


Yes you can! Details are explained in the chapter on classes. 


“https://esdiscuss.org/topic/nailing-object-property- order 
*http://www.ecma-international.org/ecma-262/6.0/#sec-array-exotic- objects 


*http://www.ecma-international.org/ecma-262/6.0/#sec-ordinary-object-internal-methods-and-internal-slots-ownpropertykeys 


16. Classes 


This chapter explains how ES6 classes work. 


16.1 Overview 


A class and a subclass: 


class Point { 
constructor(x, y) { 
this.x = x; 
this.y = y; 
} 
toString() { 
return `(${this.x}, ${this.y})`; 


class ColorPoint extends Point { 
constructor (x, y, color) { 
super (x, y); 
this.color = color; 
} 
toString() { 
return super.toString() + ' in ' + this.color; 


Under the hood, ES6 classes are not something that is radically new: They mainly provide more 
convenient syntax to create old-school constructor functions. You can see that if you use typeof: 


> typeof Point 
'function' 


Using the classes: 


Classes 


> let cp = new ColorPoint(25, 8, 'green'); 
g 


> cp.toString(); 
'(25, 8) in green' 


> cp instanceof ColorPoint 
true 

> cp instanceof Point 

true 


16.2 The essentials 


16.2.1 Base classes 


A class is defined like this in ECMAScript 6: 


class Point { 
constructor(x, y) { 
this.x = x; 
this.y = y; 
} 
toString() { 
return `(${this.x}, ${this.y})`; 


You use this class just like an ES5 constructor function: 


> var p = new Point(25, 8); 
> p.toString() 
'(25, 8)' 


In fact, the result of a class definition is a function: 


> typeof Point 
'function' 


212 


However, you can only invoke a class via new, not via a function call (the rationale behind this is 


explained later): 
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> Point() 
TypeError: Classes can’t be function-called 


$$ In the spec, function-calling classes is prevented in the internal method [[Ca11]]' of 
4$ function objects. 


16.2.1.1 Class declarations are not hoisted 


Function declarations are hoisted: When entering a scope, the functions that are declared in it are 
immediately available — independently of where the declarations happen. That means that you can 
call a function that is declared later: 


foo(); // works, because ‘foo’ is hoisted 


function foo() {} 


In contrast, class declarations are not hoisted. Therefore, a class only exists after execution reached 
its definition and it was evaluated. Accessing it beforehand leads to a ReferenceError: 


new Foo(); // ReferenceError 


class Foo {} 


The reason for this limitation is that classes can have an extends clause whose value is an arbitrary 
expression. That expression must be evaluated in the proper “location”, its evaluation can’t be 
hoisted. 


Not having hoisting is less limiting than you may think. For example, a function that comes before 
a class declaration can still refer to that class, but you have to wait until the class declaration has 
been evaluated before you can call the function. 


*http://www.ecma-international.org/ecma-262/6.0/#sec-ecmascript-function- objects-call-thisargument-argumentslist 
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function functionThatUsesBar() { 
new Bar(); 


functionThatUsesBar(); // ReferenceError 
class Bar {} 
functionThatUsesBar(); // OK 


16.2.1.2 Class expressions 


Similarly to functions, there are two kinds of class definitions, two ways to define a class: class 
declarations and class expressions. 


Also similarly to functions, the identifier of a class expression is only visible within the expression: 


const MyClass = class Me ( 
getClassName() { 
return Me.name; 


35 

let inst = new MyClass(); 

console. lLog(inst.getClassName()); // Me 

console. log(Me.name); // ReferenceError: Me is not defined 


16.2.2 Inside the body of a class definition 


A class body can only contain methods, but not data properties. Prototypes having data properties 
is generally considered an anti-pattern, so this just enforces a best practice. 


16.2.2.1 constructor, static methods, prototype methods 


Let’s examine three kinds of methods that you often find in class definitions. 


class Foo { 

constructor (prop) { 
this.prop = prop; 

} 

static staticMethod() { 
return 'classy'; 

} 

prototypeMethod() { 
return 'prototypical'; 
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} 


} 
let foo = new Foo(123); 


The object diagram for this class declaration looks as follows. Tip for understanding it: [ [Proto- 
type] ] is an inheritance relationship between objects, while prototype is a normal property whose 
value is an object. The property prototype is only special because the new operator uses its value 
as the prototype for instances it creates. 


Function.prototype Object.prototype 


Foo.prototype : Object 


[Prototype] | e 
prototypeMethod | function() {...} 


Foo : Function 


[[Prototype]] 


First, the pseudo-method constructor. This method is special, as it defines the function that 
represents the class: 


> Foo === Foo.prototype.constructor 
true 

> typeof Foo 

'function' 


It is sometimes called a class constructor. It has features that normal constructor functions don't 
have (mainly the ability to constructor-call its super-constructor via super (), which is explained 
later). 


Second, static methods. Static properties (or class properties) are properties of Foo itself. If you 
prefix a method definition with static, you create a class method: 
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> typeof Foo.staticMethod 
'function' 

> Foo.staticMethod() 
"“classy' 


Third, prototype methods. The prototype properties of Foo are the properties of Foo. prototype. 
They are usually methods and inherited by instances of Foo. 


> typeof Foo.prototype.prototypeMethod 
'function' 

> foo.prototypeMethod() 

"prototypical! 


16.2.2.2 Static data properties 


For now, classes only let you create static methods, but not static data properties. There are two 
work-arounds for that. 


First, you can manually add a static property: 


class Point { 
constructor (x, y) { 
this.x = x; 
this.y = y; 


} 
Point.ZERO = new Point(0, 0); 


Second, you can create a static getter: 


class Point { 
constructor (x, y) { 
this.x = x; 
this.y = y; 
} 
static get ZERO() { 
return new Point(0, 0); 


In both cases, you get a property Point.ZERO that you can read. In the former case, you could 
use Object.defineProperty() to create a read-only property, but I like the simplicity of an 
assignment. 
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16.2.2.3 Getters and setters 


The syntax for getters and setters is just like in ECMAScript 5 object literals’: 


class MyClass { 
get prop() { 
return 'getter'; 
} 
set prop(value) { 
console. log('setter: '+value); 


} 
You use MyClass as follows. 


> let inst = new MyClass(); 
> inst.prop = 123; 

setter: 123 

> inst.prop 

'getter' 


16.2.2.4 Computed method names 


You can define the name of a method via an expression, if you put it in square brackets. For example, 
the following ways of defining Foo are all equivalent. 


class Foo() { 
myMethod() {} 


class Foo() { 
['my'+'Method']() {} 


const m = 'myMethod'; 
class Foo() { 

MO {} 
} 


Several special methods in ECMAScript 6 have keys that are symbols. Computed method names 
allow you to define such methods. For example, if an object has a method whose key is Sym- 
bol. iterator, it is iterable. That means that its contents can be iterated over by the for-of loop 
and other language mechanisms. 


*http://speakingjs.com/es5/ch17.html#getters_setters 
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class IterableClass { 
[Symbol .iterator]() 4 


} 


16.2.2.5 Generator methods 


If you prefix a method definition with an asterisk (x), it becomes a generator method. Among other 
things, a generator is useful for defining the method whose key is Symbol. iterator. The following 
code demonstrates how that works. 


class IterableArguments { 
constructor(...args) { 
this.args = args; 
} 
x [Symbol.iterator]() { 
for (let arg of this.args) { 
yield arg; 


for (let x of new IterableArguments('hello', 'world')) { 
console. log(x) ; 


// Output: 
// hello 
// world 


16.2.3 Subclassing 


The extends clause lets you create a subclass of an existing constructor (which may or may not 
have been defined via a class): 
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class Point { 
constructor(x, y) { 
this.x = x; 
this.y = y; 
} 
toString() { 
return `(${this.x}, ${this.y})`; 


class ColorPoint extends Point { 
constructor (x, y, color) { 
super (x, y); // (A) 
this.color = color; 
} 
toString() { 
return super.toString() + ' in ' + this.color; // (B) 


Again, this class is used like you'd expect: 


> let cp = new ColorPoint(25, 8, 'green'); 
> cp.toString() 
'(25, 8) in green' 


> cp instanceof ColorPoint 
true 

> cp instanceof Point 

true 


There are two kinds of classes: 


e Point is a base class, because it doesn’t have an extends clause. 
e ColorPoint is a derived class. 


There are two ways of using super: 


e A class constructor (the pseudo-method constructor in a class definition) uses it like a 
function call (super (+++ )), in order to make a super-constructor call (line A). 

e Method definitions (in object literals or classes, with or without static) use it like property 
references (super. prop) or method calls (super .method( : - + )), in order to refer to super- 
properties (line B). 
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16.2.3.1 The prototype of a subclass is the superclass 


The prototype of a subclass is the superclass in ECMAScript 6: 


> Object.getPrototypeOf (ColorPoint) === Point 
true 


That means that static properties are inherited: 


class Foo { 
static classMethod() { 
return 'hello'; 


class Bar extends Foo { 


} 
Bar.classMethod(); // 'hello' 


You can even super-call static methods: 


class Foo { 
static classMethod() { 
return 'hello'; 


class Bar extends Foo { 
static classMethod() { 
return super.classMethod() + ', too'; 


} 
Bar.classMethod(); // 'hello, too' 


16.2.3.2 Super-constructor calls 


In a derived class, you must call super () before you can use this: 
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class Foo {} 


class Bar extends Foo { 
constructor(num) { 
let tmp = num x 2; // OK 
this.num = num; // ReferenceError 
super (); 
this.num = num; // OK 


Implicitly leaving a derived constructor without calling super () also causes an error: 


class Foo {} 


class Bar extends Foo { 
constructor() { 


} 


let bar = new Bar(); // ReferenceError 


16.2.3.3 Overriding the result of a constructor 


Just like in ES5, you can override the result of a constructor by explicitly returning an object: 


class Foo { 
constructor () { 
return Object.create (null); 


} 


console. log(new Foo() instanceof Foo); // false 


If you do so, it doesn't matter whether this has been initialized or not. In other words: you don't 
have to call super () in a derived constructor if you override the result in this manner. 


16.2.3.4 Default constructors for classes 


If you don't specify a constructor for a base class, the following definition is used: 
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constructor() {} 
For derived classes, the following default constructor is used: 


constructor(...args) { 
super(...args); 


} 
16.2.3.5 Subclassing built-in constructors 


In ECMAScript 6, you can finally subclass all built-in constructors (there are work-arounds for ES5?, 
but these have significant limitations). 


For example, you can now create your own exception classes (that will inherit the feature of having 
a stack trace in most engines): 


class MyError extends Error { 


} 


throw new MyError('Something happened!'); 
You can also create subclasses of Array whose instances properly handle length: 


class MyArray extends Array { 
constructor (len) { 
super (len); 


// Instances of of `MyArray` work like real Arrays: 
let myArr = new MyArray(0); 
console.log(myArr.length); // 0 

myArr[o] = 'foo'; 

console. log(myArr.length); // 1 


Note that subclassing built-in constructors is something that engines have to support natively, you 
won't get this feature via transpilers. 


16.3 The details of classes 


What we have seen so far are the essentials of classes. You only need to read on if you are interested 
how things happen under the hood. Let’s start with the syntax of classes. The following is a slightly 
modified version of the syntax shown in Sect. A.4 of the ECMAScript 6 specification”. 


$http://speakingjs.com/es5/ch28.html 
“http://www.ecma-international.org/ecma-262/6.0/#sec-functions-and-classes 
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ClassDeclaration: 

"class" BindingIdentifier ClassTail 
ClassExpression: 

"class" BindingIdentifier? ClassTail 


ClassTail: 

ClassHeritage? "{" ClassBody? "}" 
ClassHeritage: 

"extends" AssignmentExpression 
ClassBody: 

ClassElement+ 
ClassElement: 

MethodDefinition 

"static" MethodDefinition 


Well 
a 


MethodDefinition: 


PropName "(" FormalParams ")" "{" FuncBody "}" 

"x" PropName "(" FormalParams ")" "{" GeneratorBody "}" 
"set" PropName "(" ")" "{" FuncBody "}" 

"set" PropName "(" PropSetParams ")" "{" FuncBody "}" 


PropertyName: 
LiteralPropertyName 
ComputedPropertyName 
LiteralPropertyName: 
IdentifierName /x foo */ 
StringLiteral /* "foo" x*/ 
NumericLiteral /*x 123.45, OxFF x/ 
ComputedPropertyName: 
"[" Expression "]" 


Two observations: 
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e The value to be extended can be produced by an arbitrary expression. Which means that you'll 


be able to write code such as the following: 


class Foo extends combine(MyMixin, MySuperClass) {} 


e Semicolons are allowed between methods. 
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16.3.1 Various checks 


e Error checks: the class name cannot be eval or arguments; duplicate class element names are 
not allowed; the name constructor can only be used for a normal method, not for a getter, 
a setter or a generator method. 


e Classes can’t be function-called. They throw a TypeException if they are. 
e Prototype methods cannot be used as constructors: 


class C { 


mO {} 
} 
new C.prototype.m(); // TypeError 


16.3.2 Attributes of properties 


Class declarations create (mutable) let bindings. For a given class Foo: 


e Static methods Foo.» are writable and configurable, but not enumerable. Making them 
writable allows for dynamic patching. 
e A constructor and the object in its property prototype have an immutable link: 
- Foo.prototype is non-writeable, non-enumerable, non-configurable. 
- Foo.prototype.constructor is non-writeable, non-enumerable, non-configurable. 
e Prototype methods Foo.prototype.x are writable and configurable, but not enumerable. 


Note that method definitions in object literals produce enumerable properties. 


16.4 The details of subclassing 
In ECMAScript 6, subclassing looks as follows. 


class Point { 
constructor(x, y) { 
this.x = x; 
this.y = y; 


class ColorPoint extends Point { 
constructor(x, y, color) { 
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super (x, y); 
this.color = color; 


} 


let cp = new ColorPoint(25, 8, 'green'); 


This code produces the following objects. 
Function.prototype 


[[Prototype]] 
prototype 


[[Prototype]] 


ColorPoint 


prototype 
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Object.prototype 


[[Prototype]] 


Point.prototype 


[[Prototype]] 


ColorPoint. prototype 


[[Prototype]] 


The next subsection examines the prototype chains (in the two columns), the subsection after that 


examines how cp is allocated and initialized. 


16.4.1 Prototype chains 


In the diagram, you can see that there are two prototype chains (objects linked via the [[Proto- 
type]] relationship, which is an inheritance relationship): 


e Left column: classes (functions). The prototype of a derived class is the class it extends. The 
prototype of a base class is Function. prototype, which is also the prototype of functions: 
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> const getProto = Object.getPrototype0f.bind(Object); 


> getProto(Point) === Function.prototype 

true 

> getProto(function () {}) === Function.prototype 
true 


e Right column: the prototype chain of the instance. The whole purpose of a class is to set up 
this prototype chain. The prototype chain ends with Object. prototype (whose prototype is 
null), which is also the prototype of objects created via object literals: 


> const getProto = Object.getPrototypeOf.bind(Object) ; 


> getProto(Point.prototype) === Object.prototype 
true 

> getProto({}) === Object.prototype 

true 


The prototype chain in the left column leads to static properties being inherited. 


16.4.2 Allocating and initializing instances 


The data flow between class constructors is different from the canonical way of subclassing in ES5. 
Under the hood, it roughly looks as follows. 


// Instance is allocated here 

function Point(x, y) { 
// Performed before entering this constructor: 
this = Object.create(new.target.prototype) ; 


this. 
this.y = y; 


x 
l 


= x; 


function ColorPoint(x, y, color) { 
// Performed before entering this constructor: 
this = uninitialized; 


this = Reflect.construct(Point, [x, y], new.target); // (A) 
// super(x, y); 
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this. 


} 
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color = color; 


Object.setPrototypeOf (ColorPoint, Point); 


let cp = 


Reflect.construct( // (B) 
ColorPoint, [25, 8, 'green'], 
ColorPoint) ; 


// let cp = new ColorPoint(25, 8, 'green'); 


The instance object is created in different locations in ES6 and ES5: 


¢ In ES6, it is created in the base constructor, the last in a chain of constructor calls. 


e In ESS, it is created in the operand of new, the first in a chain of constructor calls. 


The previous code uses two new ES6 features: 


e new.target is an implicit parameter that all functions have. It is to constructor calls what 
this is to method calls. 


If a constructor has been directly invoked via new, its value is that constructor (line B). 
If a constructor was called via super (), its value is the new. target of the constructor 
that made the call (line A). 

During a normal function call, it is undef ined. That means that you can use new. target 
to determine whether a function was function-called or constructor-called (via new). 
Inside an arrow function, new. target refers to the new. target of the surrounding 
non-arrow function. 


e Reflect.construct() lets you do a constructor call while specifying new. target via the 
last parameter. 


The advantage of this way of subclassing is that it enables normal code to subclass built-in 
constructors (such as Error and Array). A later section explains why a different approach was 


necessary. 


16.4.2.1 Safety checks 


e this originally being uninitialized in derived constructors means that an error is thrown if 
they access this in any way before they have called super (). 


e Once this is initialized, calling super () produces a ReferenceError. This protects you 
against calling super () twice. 


e If a constructor returns implicitly (without a return statement), the result is this. If this 
is uninitialized, a ReferenceError is thrown. This protects you against forgetting to call 
super(). 
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e If a constructor explicitly returns a non-object (including undefined and null), the result 
is this (this behavior is required to remain compatible with ES5 and earlier). If this is 
uninitialized, a TypeError is thrown. 

e If a constructor explicitly returns an object, it is used as its result. Then it doesn’t matter 
whether this is initialized or not. 


16.4.2.2 The extends clause 


Let’s examine how the extends clause influences how a class is set up (Sect. 14.5.14 of the spec’). 


The value of an extends clause must be “constructible” (invocable via new). nu11 is allowed, though. 


class C { 


} 


e Constructor kind: base 

e Prototype of C: Function.prototype (like a normal function) 

e Prototype of C.prototype: Object.prototype (which is also the prototype of objects 
created via object literals) 


class C extends B { 


} 


¢ Constructor kind: derived 
e Prototype of C: B 
e Prototype of C. prototype: B.prototype 


class C extends Object { 
} 


e Constructor kind: derived 
e Prototype of C: Object 
e Prototype of C.prototype: Object.prototype 


Note the following subtle difference with the first case: If there is no extends clause, the class is a 
base class and allocates instances. Ifa class extends Object, itis a derived class and Object allocates 
the instances. The resulting instances (including their prototype chains) are the same, but you get 
there differently. 


"http://www.ecma-international.org/ecma-262/6.0/*sec-runtime-semantics-classdefinitionevaluation 
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class C extends null { 


} 


¢ Constructor kind: derived 
e Prototype of C: Function.prototype 
e Prototype of C.prototype: null 


Such a class lets you avoid Object.prototype in the prototype chain. But that is rarely useful. 
Furthermore, you have to be careful: new-calling such a class leads to an error, because the default 
constructor makes a super-constructor call and Function.prototype (the super-constructor) can't 
be constructor-called. The only way to make the error go away is by adding a constructor that 
returns an object: 


class C extends null { 
constructor() { 
let _this = Object.create(new.target.prototype) ; 
return _this; 


new. target ensures that C can be subclassed properly — the prototype of _this will always be the 
operand of new. 


16.4.3 Why can't you subclass built-in constructors in ES5? 


In ECMAScript 5, most built-in constructors can't be subclassed (several work-arounds exist'). 


To understand why, let’s use the canonical ES5 pattern to subclass Array. As we shall soon find out, 
this doesn’t work. 


function MyArray(len) { 
Array.call(this, len); // (A) 
} 
MyArray.prototype = Object.create(Array.prototype) ; 


Unfortunately, if we instantiate MyAr ray, we find out that it doesn’t work properly: The instance 
property length does not change in reaction to us adding Array elements: 


*http://speakingjs.com/es5/ch28.html 
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> var myArr = new MyArray(0); 
myArr. length 


> 
0 
> myArr[0] = 'foo'; 
> myArr.length 

0 


There are two obstracles that prevent myArr from being a proper Array. 


First obstacle: initialization. The this you hand to the constructor Array (in line A) is completely 
ignored. That means you can't use Array to set up the instance that was created for MyArray. 


> var a= []; 

> var b = Array.call(a, 3); 

>a !== b // a is ignored, b is a new object 
true 

> b. length // set up correctly 

3 

> a. length // unchanged 

0 


Second obstacle: allocation. The instance objects created by Array are exotic (a term used by 
the ECMAScript specification for objects that have features that normal objects don’t have): Their 
property length tracks and influences the management of Array elements. In general, exotic objects 
can be created from scratch, but you can't convert an existing normal object into an exotic one. 
Unfortunately, that is what Array would have to do, when called in line A: It would have to turn 
the normal object created for MyArray into an exotic Array object. 


16.4.3.1 The solution: ES6 subclassing 
In ECMAScript 6, subclassing Array looks as follows: 
class MyArray extends Array { 


constructor(len) { 
super (Len) ; 


This works (but it’s not something that ES6 transpilers can support, it depends on whether a 
JavaScript engine supports it natively): 
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let myArr = new MyArray(0); 
myArr. length 


myArr[0] = 'foo'; 
myArr. Length 


e V Vv OV V 


We can now see how the ES6 approach to subclassing circumvents the obstacles: 


e Allocation happens in the base constructor, which means that Array can allocate an exotic 
object. While most of the new approach is due to how derived constructors behave, this step 
requires that a base constructor is aware of new. target and makes new. target. prototype 
the protoype of the allocated instance. 


Initialization also happens in the base constructor, a derived constructor receives an initialized 
object and works with that one instead of passing its own instance to the super-constructor 
and requiring it to set it up. 


16.4.4 Referring to super-properties in methods 


The following ES6 code makes a super-method call in line B. 


class Point { 
constructor (x, y) { 
this.x = x; 
this.y = y; 
} 
toString() { // (A) 
return `(${this.x}, ${this.y})`; 


class ColorPoint extends Point { 
constructor (x, y, color) { 
super (x, y); 
this.color = color; 
} 
toString() { 
return super.toString() // (B) 
+ ' in ' + this.color; 
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let cp = new ColorPoint(25, 8, 'green'); 
console.log(cp.toString()); // (25, 8) in green 


To understand how super-calls work, let’s look at the object diagram of cp: 


Object.prototype 


Point.prototype 


TO CN 
function() {...} 


ColorPoint.prototype 


[[Prototypel] | è 
function() {...} 


Cc 


p 
[[Prototype]] 


ColorPoint.prototype.toString makes a super-call (line B) to the method (starting in line A) 
that it has overridden. Let's call the object, in which a method is stored, the home object of that 
method. For example, ColorPoint.prototypeisthe home object of ColorPoint.prototype.toString(). 


The super-call in line B involves three steps: 


1. Start your search in the prototype of the home object of the current method. 

2. Look for a method whose name is toString. That method may be found in the object where 
the search started or later in the prototype chain. 

3. Call that method with the current this. The reason for doing so is: the super-called method 
must be able to access the same instance properties (in our example, the properties of cp). 


Note that even if you are only getting or setting a property (not calling a method), you still have to 
consider this in step +3, because the property may be implemented via a getter or a setter. 
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Let's express these steps in three different, but equivalent, ways: 


// Variation 1: super-method calls in ES5 
var result = Point.prototype.toString.call(this) // steps 1,2,3 


// Variation 2: ES5, refactored 

var superObject = Point.prototype; // step 1 

var superMethod = superObject.toString; // step 2 
var result = superMethod.call(this) // step 3 


// Variation 3: ES6 

var homeObject = ColorPoint.prototype; 

var superObject = Object.getPrototypeOf(homeObject); // step 1 
var superMethod = superObject.toString; // step 2 

var result = superMethod.call(this) // step 3 


Variation 3 is how ECMAScript 6 handles super-calls. This approach is supported by two internal 
bindings’ that the environments of functions have (environments provide storage space, so-called 
bindings, for the variables in a scope): 


e [[thisValue]]: This internal binding also exists in ECMAScript 5 and stores the value of 
this. 

e [[HomeObject] ]: Refers to the home object of the environment's function. Filled in via an 
internal property [[HomeObject]] that all methods have that use super. Both the binding 
and the property are new in ECMAScript 6. 


0 Methods are a special kind of function now 


In a class, a method definition that uses super creates a special kind of function: It is still a 
function, but it has the internal property [ [HomeObject] ]. That property is set up by the 
method definition and can't be changed in JavaScript. Therefore, you can't meaningfully 
move such a method to a different object. (But maybe it’ll be possible in a future version 
of ECMAScript.) 


16.4.4.1 Where can you use super? 


Referring to super-properties is handy whenever prototype chains are involved, which is why you 
can use it in method definitions inside object literals and class definitions (the class can be derived 
or not, the method can be static or not). 


Using super to refer to a property is not allowed in function declarations, function expressions and 
generator functions. 


"http://www.ecma-international.org/ecma-262/6.0/#sec-function-environment-records 
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16.4.4.2 A method that uses super can't be moved 


You can't move a method that uses super: Such a method has an internal property [[Home0bject]] 
that ties it to the object it was created in. If you move it via via an assignment, it will continue to 
refer to the super-properties of the original object. In future ECMAScript versions, there may be a 
way to transfer such a method, too. 


16.5 Constructor calls explained via JavaScript code 


The JavaScript code in this section is a much simplified version of how the specification describes 
constructor calls and super-constructor calls. It may be interesting to you if you prefer code to 
explanations in human language. Before we can delve into the actual functionality, we need to 
understand a few other mechanisms. 


16.5.1 Internal variables and properties 


The specification writes internal variables and properties in double brackets ([ [Foo] ]). In the code, 
I use double underscores, instead (__Foo__). 


Internal variables used in the code: 


e [[NewTarget]]: The operand of the new operator that triggered the current constructor call 
(passed on if [[Construct]] is called recursively via super ()). 

e [[thisValue] ]: Stores the value of this. 

e [[Function0bject]]: Refers to the function that is currently executed. 


Internal properties used in the code: 


e [[Construct]]: All constructor functions (including those created by classes) have this own 
(non-inherited) method. It implements constructor calls and is invoked by new. 

e [[ConstructorKind]]: A property of constructor functions whose value is either 'base' 
or 'derived'. 


16.5.2 Environments 


Environments provide storage space for variables, there is one environment per scope. Environments 
are managed as a stack. The environment on top of that stack is considered active. The following 
code is a sketch of how environments are handled. 
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px 
* Function environments are special, they have a few more 
x internal variables than other environments. 
x (` Environment) is not shown here) 
*/ 
class FunctionEnvironment extends Environment { 
constructor (Func) { 
// [[FunctionO0bject]] is a function-specific 
// internal variable 
this.__Function0bject__ = Func; 


px 
x Push an environment onto the stack 
x/ 


function PushEnvironment(env) { °°: } 


px 
x Pop the topmost environment from the stack 
*/ 


function PopEnvironment() { =: } 


px 
x Find topmost function environment on stack 
*/ 


function GetThisEnvironment() { °°: } 


16.5.3 Constructor calls 


Let's start with the default way (ES6 spec Sect. 9.2.3°) in which constructor calls are handled for 
functions: 


Shttp://www.ecma-international.org/ecma-262/6.0/#sec-ecmascript-function-objects-construct-argumentslist-newtarget 
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px 
x ALL constructible functions have this own method, 
x it is called by the ‘new’ operator 
*/ 
AnyFunction.__Construct__ = function (args, newTarget) { 
let Constr = this; 
let kind = Constr.__ConstructorKind__; 


let env = new FunctionEnvironment(Constr); 


env.__NewTarget__ = newTarget; 
if (kind === 'base') { 

env.__thisValue__ = Object.create(newTarget. prototype) ; 
} else { 


// While "this" is uninitialized, getting or setting it 
// throws a 'ReferenceError” 
env.__thisValue__ = uninitialized; 


PushEnvironment (env) ; 
let result = Constr(...args); 
PopEnvironment () ; 


// Let’s pretend there is a way to tell whether 'result' 
// was explicitly returned or not 
if (WasExplicitlyReturned(result)) { 
if (isObject(result)) { 
return result; 


} 
// Explicit return of a primitive 
if (kind === 'base') { 
// Base constructors must be backwards compatible 
return env.__thisValue__; // always initialized! 
} 
throw new TypeError(); 
} 
// Implicit return 
if (env.__thisValue__ === uninitialized) { 
throw new ReferenceError(); 
} 


return env.__thisValue__; 
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16.5.4 Super-constructor calls 


Super-constructor calls are handled as follows (ES6 spec Sect. 12.3.5.1°). 


px 
* Handle super-constructor calls 
*/ 
function super(...args) { 
let env = GetThisEnvironment(); 
let newTarget = env.__NewTarget__; 
let activeFunc = env.__Function0bject__; 
let superConstructor = Object.getPrototype0f (activeFunc) ; 


env.__thisValue__ = superConstructor 
.__Construct__(args, newTarget) ; 


16.6 The species pattern 


One more mechanism of built-in constructors has been made extensible in ECMAScript 6: If a 
method such as Array. prototype.map() returns a fresh instance, what constructor should it use 
to create that instance? 


Helper functions used in the following three sections: 


function isObject(value) { 


return (value !== null 
&& (typeof value === 'object' 
|| typeof value === 'function')); 
} 
px 


x Spec-internal operation that determines whether 'x' can be used as a construc 
tor, 
*/ 


function isConstructor(x) { 


*http://www.ecma-international.org/ecma-262/6.0/#sec-super-keyword-runtime-semantics-evaluation 
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16.6.1 The standard species pattern 


The pattern for customizing instances created by methods such as Array .prototype.map() is 
called the species pattern: 


e If this. constructor [Symbol.species] exists, use it as a constructor for the new instance. 
e Otherwise, use a default constructor (e.g. Array for Arrays). 


Implemented in JavaScript, this pattern would look like this: 


function SpeciesConstructor(0, defaultConstructor) ( 
let C = O.constructor; 
if (C === undefined) { 
return defaultConstructor ; 
} 
if (! isObject(C)) { 
throw new TypeError(); 


} 

let S = C[Symbol.species]; 

if (S === undefined || S === null) ( 
return defaultConstructor ; 

} 


if (! isConstructor(S)) { 
throw new TypeError(); 


} 


return S; 


re ced The standard species pattern for Arrays is implemented in the spec via the operation 
$ SpeciesConstructor()”. 


16.6.2 The species pattern for Arrays 


This is an approximation of how the species pattern is used for Arrays: 


“http://www.ecma-international.org/ecma-262/6.0/*sec-speciesconstructor 
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function ArraySpeciesCreate(originalArray, length) { 
let C = undefined; 
if (Array. isArray(originalArray)) ( 
C = originalArray.constructor; 
if (isObject(c)) { 
C = C[Symbol.species] ; 


t 

} 

if (C === undefined || C === null) { 
return new Array(length); 

} 


if (! IsConstructor(C)) { 
throw new TypeError(); 


} 


return new C(length); 


Array .prototype.map() creates the Array it returns via ArraySpeciesCreate(this, this.length) 


re ted The species pattern for Arrays is implemented in the spec via the operation 
$ ArraySpeciesCreate()”. 


16.6.3 The species pattern in static methods 


Promises use a variant of the species pattern for static methods such as Promise.all ()””: 


let C = this; // default 
if (! isO0bject(C)) { 
throw new TypeError(); 
} 
// The default can be overridden via the property `C[Symbol.species]` 
let S = C[Symbol.species] ; 
if (S !== undefined && S !== null) { 
C = S; 
} 
if (!IsConstructor(C)) { 
throw new TypeError(); 
} 


let instance = new C(:-:); 


“http://www.ecma-international.org/ecma-262/6.0/#sec-arrayspeciescreate 
“http://www.ecma-international.org/ecma-262/6.0/#sec-promise.all 
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16.6.4 Overriding the default species in subclasses 


This is the default getter for the property [Symbol . species]: 


static get [Symbol.species]() { 
return this; 


This default getter is implemented by the built-in classes Array, ArrayBuffer, Map, Promise, 
RegExp, Set and %TypedAr ray%. It is automatically inherited by subclasses of these built-in classes. 


There are two ways in which you can override the default species: with a constructor of your 
choosing or with null. 


16.6.4.1 Setting the species to a constructor of your choosing 


You can override the default species via a static getter (line A): 


class MyArrayl extends Array { 
static get [Symbol.species]() { // (A) 
return Array; 


As a result, map() returns an instance of Array: 


let result1 = new MyArray1().map(x => x); 
console. log(resultl instanceof Array); // true 


If you don’t override the default species, map() returns an instance of the subclass: 


class MyArray2 extends Array { } 


let result2 = new MyArray2().map(x => x); 
console. log(result2 instanceof MyArray2); // true 


16.6.4.1.1 Specifying the species via a data property Ifyou don't want to use a static getter, you 
need to use Object .defineProperty(). You can’t use assignment, as there is already a property 
with that key that only has a getter. That means that it is read-only and can't be assigned to. 


For example, here we set the species of MyArray1 to Array: 
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Object.defineProperty( 
MyArray1, Symbol.species, { 
value: Array 


$»; 
16.6.4.2 Setting the species to null 


If you set the species to null then the default constructor is used (which one that is depends on 
which variant of the species pattern is used, consult the previous sections for more information). 


class MyArray3 extends Array { 
static get [Symbol.species]() { 
return null; 


} 


let result3 = new MyArray3().map(x => x); 
console.log(result3 instanceof Array); // true 


16.7 FAQ: classes 


16.7.1 Why can't classes be function-called? 


Function-calling classes is currently forbidden. That was done to keep options open for the future, 
to eventually add a way to handle function calls via classes. One possibility is to do so via a special 
method (e.g. [Symbol. functionCal1]). 


16.7.2 How do instantiate a class, given an Array of arguments? 


What is the analog of Function.prototype.apply() for classes? That is, if I have a class 
TheClass and an Array args of arguments, how do I instantiate TheClass? 


One way of doing so is via the spread operator (. . .): 


function instantiate(TheClass, args) { 
return new TheClass(...args); 


} 


Another option is to use Reflect.construct(): 
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function instantiate(TheClass, args) ( 
return Reflect.construct(TheClass, args); 


16.7.3 How do | manage private data for classes? 


Two ES5 ways'* of keeping data private work for classes, too: 


1. You can keep private data in the environment of a class constructor. I have always disliked 
how this forces you to add privileged methods to instances. 

2. You can use a naming convention (e.g. a prefixed underscore) to mark private properties. I like 
this approach. It doesn’t give you complete protection and slightly clutters up the property 
namespace, but it leads to simple code. 


In ECMAScript 6, you can additionally use WeakMaps for private data, which gives you the complete 
protection of approach #1, but with more elegant code. This is an example of how to do that, details 
are explained in the chapter on WeakMaps: 


let _counter = new WeakMap() ; 
let _action = new WeakMap() ; 
class Countdown { 
constructor(counter, action) { 
_counter.set(this, counter); 
_action.set(this, action); 


} 

dec() { 
let counter = _counter.get(this); 
if (counter < 1) return; 
counter--; 
_counter.set(this, counter); 
if (counter === 0) { 

_action.get(this)(); 

} 

} 


16.7.4 What is next for classes? 


The design motto for classes was “maximally minimal”. Several advanced features were discussed, 
but ultimately discarded in order to get a design that would be unanimously accepted by TC39. 


13 Speaking JS] “Keeping Data Private” 
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Upcoming versions of ECMAScript can now extend this minimal design — classes will provide a 
foundation for features such as traits (or mixins), value objects (where different objects are equal if 
they have the same content) and const classes (that produce immutable instances). 


16.8 The pros and cons of classes 


Classes are controversial within the JavaScript community: On one hand, people coming from class- 
based languages are happy that they don't have to deal with JavaScript's unconventional inheritance 
mechanisms, anymore. On the other hand, there are many JavaScript programmers who argue that 
what's complicated about JavaScript is not prototypal inheritance, but constructors. 


ES6 classes provide a few clear benefits: 


e They are backwards compatible with much of the current code. 
e Compared to constructors and constructor inheritance, classes make it easier for beginners to 
get started. 


Subclassing is supported within the language. 
e Built-in constructors are subclassable. 


No library for inheritance is needed, anymore; code will become more portable between 

frameworks. 

e They provide a foundation for advanced features in the future: traits (or mixins), immutable 
instances, etc. 

e They help tools that statically analyze code (IDEs, type checkers, style checkers, etc.). 


Let’s look at a few common complaints about ES6 classes. You will see me agree with most of them, 
but I also think that they benefits of classes much outweigh their disadvantages. I’m glad that they 
are in ES6 and I recommend to use them. 


16.8.1 Complaint: ES6 classes obscure the true nature of 
JavaScript inheritance 


Yes, ES6 classes do obscure the true nature of JavaScript inheritance. There is an unfortunate 
disconnect between what a class looks like (its syntax) and how it behaves (its semantics): It looks 
like an object, but it is a function. My preference would have been for classes to be constructor 
objects, not constructor functions. I explore that approach in the Proto.js project'*, via a tiny 
library (which proves how good a fit this approach is). 


However, backwards-compatibility matters, which is why classes being constructor functions also 
makes sense. That way, ES6 code and ES5 are more interoperable. 


“https://github.com/rauschma/proto-js 


Classes 244 


The disconnect between syntax and semantics will cause some friction in ES6 and later. But you can 
lead a comfortable life by simply taking ES6 classes at face value. I don’t think the illusion will ever 
bite you. Newcomers can get started more quickly and later read up on what goes on behind the 
scenes (after they are more comfortable with the language). 


16.8.2 Complaint: Classes provide only single inheritance 


Classes only give you single inheritance, which severely limits your freedom of expression w.r.t. 
object-oriented design. However, the plan has always been for them to be the foundation of a 
multiple-inheritance mechanism such as traits. 


0 traits.js: traits library for JavaScript 


Check out traits.js*? if you are interested in how traits work (they are similar to mixins, 
which you may be familiar with). 


Then a class becomes an instantiable entity and a location where you assemble traits. Until that 
happens, you will need to resort to libraries if you want multiple inheritance. 


16.8.3 Complaint: Classes lock you in, due to mandatory new 


If you want to instantiate a class, you are forced to use new in ES6. That means that you can't switch 
from a class to a factory function without changing the call sites. That is indeed a limitation, but 
there are two mitigating factors: 


e You can override the default result returned by the new operator, by returning an object from 
the constructor method of a class. 

¢ Due to its built-in modules and classes, ES6 makes it easier for IDEs to refactor code. Therefore, 
going from new to a function call will be simple. Obviously that doesn’t help you if you don’t 


control the code that calls your code, as is the case for libraries. 


Therefore, classes do somewhat limit you syntactically, but, once JavaScript has traits, they won’t 
limit you conceptually (w.r.t. object-oriented design). 


16.9 Further reading 


The following document is an important source of this chapter: 


e “Instantiation Reform: One last time*”, slides by Allen Wirfs-Brock. 


Bhttp://soft.vub.ac.be/-tvcutsem/traitsjs/ 
“Shttps://github.com/rwaldron/tc39-notes/blob/master/esó6/2015-01/jan2015-allen-slides.pdf 


17. Modules 


This chapter explains how the built-in modules work in ECMAScript 6. 


17.1 Overview 


In ECMAScript 6, modules are stored in files. There is exactly one module per file and one file per 
module. You have two ways of exporting things from a module. These two ways can be mixed, but 


it is usually better to use them separately. 


17.1.1 Multiple named exports 


There can be multiple named exports: 


| [------ lib.js ------ 
export const sqrt = Math.sqrt; 
export function square(x) { 
return x * x; 
} 
export function diag(x, y) { 
return sqrt(square(x) + square(y)); 


J {=s main.js ------ 

import { square, diag } from 'lib'; 
console. log(square(11))3; // 121 
console. log(diag(4, 3)); // 5 


You can also import the complete module: 
ft ae main. ]s ====== 
import * as lib from 'lib'; 


console.log(lib.square(11)); // 121 
console.log(lib.diag(4, 3)); // 5 


17.1.2 Single default export 


There can be a single default export. For example, a function: 
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f====== myFunc.js =-=-=-=-- 
export default function () { +++ } // no semicolon! 


pp ======> mainl.js ------ 


import myFunc from 'myFunc'; 
myFunc() ; 


Or a class: 


Jj] ===> MyClass.js ------ 
export default class { :-- } // no semicolon! 


e == main2.js ------ 


import MyClass from 'MyClass'; 
let inst = new MyClass(); 


Note that there is no semicolon at the end if you default-export a function or a class (which are 
anonymous declarations). 


17.1.3 Browsers: scripts versus modules 


Scripts Modules 
HTML element <script> <script type="module"> 
Top-level variables are global local to module 
Value of this at top level window undefined 
Executed synchronously asynchronously 
Import declaratively (import statement) no yes 
Import programmatically (Promise-based API) yes yes 
File extension ‚js .js 


17.2 Modules in JavaScript 


Even though JavaScript never had built-in modules, the community has converged on a simple style 
of modules, which is supported by libraries in ES5 and earlier. This style has also been adopted by 
ES6: 


e Each module is a piece of code that is executed once it is loaded. 

e In that code, there may be declarations (variable declarations, function declarations, etc.). 
— By default, these declarations stay local to the module. 
— You can mark some of them as exports, then other modules can import them. 
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e A module can import things from other modules. It refers to those modules via module 
specifiers, strings that are either: 
— Relative paths (' . . /model/user '): these paths are interpreted relatively to the location 
of the importing module. The file extension .js can usually be omitted. 
— Absolute paths ('/lib/js/helpers'): point directly to the file of the module to be 
imported. 
— Names ('util'): What modules names refer to has to be configured. 
e Modules are singletons. Even if a module is imported multiple times, only a single “instance” 
of it exists. 


This approach to modules avoids global variables, the only things that are global are module 
specifiers. 


17.2.1 ECMAScript 5 module systems 


It is impressive how well ES5 module systems work without explicit support from the language. The 
two most important (and unfortunately incompatible) standards are: 


e CommonJS Modules: The dominant implementation of this standard is in Node.js* (Node.js 
modules have a few features that go beyond CommonJS). Characteristics: 
— Compact syntax 
— Designed for synchronous loading 
— Main use: server 
e Asynchronous Module Definition (AMD): The most popular implementation of this stan- 
dard is RequireJS’. Characteristics: 
— Slightly more complicated syntax, enabling AMD to work without eval() (or a compila- 
tion step) 
— Designed for asynchronous loading 
— Main use: browsers 


The above is but a simplified explanation of ES5 modules. If you want more in-depth material, take 
a look at “Writing Modular JavaScript With AMD, CommonJS & ES Harmony”” by Addy Osmani. 


17.2.2 ECMAScript 6 modules 


The goal for ECMAScript 6 modules was to create a format that both users of CommonJS and of 
AMD are happy with: 


*http://nodejs.org/api/modules.html 
?http://requirejs.org/ 
*http://addyosmani.com/writing- modular-js/ 
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e Similarly to CommonJS, they have a compact syntax, a preference for single exports and 
support for cyclic dependencies. 

e Similarly to AMD, they have direct support for asynchronous loading and configurable 
module loading. 


Being built into the language allows ES6 modules to go beyond CommonJS and AMD (details are 
explained later): 


e Their syntax is even more compact than CommonJS's. 
e Their structure can be statically analyzed (for static checking, optimization, etc.). 
e Their support for cyclic dependencies is better than CommonJS's. 


The ES6 module standard has two parts: 


e Declarative syntax (for importing and exporting) 
e Programmatic loader API: to configure how modules are loaded and to conditionally load 
modules 


17.3 The basics of ES6 modules 


There are two kinds of exports: named exports (several per module) and default exports (one per 
module). 


17.3.1 Named exports (several per module) 


A module can export multiple things by prefixing its declarations with the keyword export. These 
exports are distinguished by their names and are called named exports. 


//------ lib.js ------ 
export const sqrt = Math.sqrt; 
export function square(x) { 
return x * xX; 
} 
export function diag(x, y) { 
return sqrt(square(x) + square(y)); 


J====== main.js ------ 

import { square, diag } from 'lib'; 
console. log(square(11))3 // 121 
console. log(diag(4, 3)); // 5 
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There are other ways to specify named exports (which are explained later), but I find this one quite 
convenient: simply write your code as if there were no outside world, then label everything that you 
want to export with a keyword. 


If you want to, you can also import the whole module and refer to its named exports via property 
notation: 


e ====>= maTM. js: ====== 

import * as lib from 'lib'; 
console.log(lib.square(11)); // 121 
console.log(lib.diag(4, 3)); // 5 


The same code in CommonJS syntax: For a while, I tried several clever strategies to be less 
redundant with my module exports in Node.js. Now I prefer the following simple but slightly verbose 
style that is reminiscent of the revealing module pattern‘: 


//------ libsjs.s==S-=5 
var sqrt = Math.sqrt; 
function square(x) { 
return x * xX; 
Í 
function diag(x, y) { 
return sqrt(square(x) + square(y)); 


} 

module.exports = { 
sqrt: sqrt, 
square: square, 
diag: diag, 

$; 

1d RES main.js -==-=--- 


var square = require('lib').square; 
var diag = require('lib').diag; 
console.log(square(11)); // 121 
console. log(diag(4, 3)); // 5 


17.3.2 Default exports (one per module) 


Modules that only export single values are very popular in the Node.js community. But they are also 
common in frontend development where you often have classes for models and components, with 


*http://christianheilmann.com/2007/08/22/again-with-the-module-pattern-reveal-something-to-the-world/ 
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one class per module. An ES6 module can pick a default export, the main exported value. Default 
exports are especially easy to import. 


The following ECMAScript 6 module “is” a single function: 


pp ==2=>=23 myFunc.js =-=-=-=-- 
export default function () {} // no semicolon! 


j {=== mainl.js ------ 


import myFunc from 'myFunc'; 
myFunc() 5 


An ECMAScript 6 module whose default export is a class looks as follows: 


J {=z MyClass.js ------ 
export default class {} // no semicolon! 


pp ======> main2.js ------ 


import MyClass from 'MyClass'; 
let inst = new MyClass(); 


There are two styles of default exports: 


1. Labels for declarations 
2. Direct exports of values (produced by expressions) 


17.3.2.1 Default export style 1: labels for declarations 


You can prefix any function declaration (or generator function declaration) or class declaration with 
the keywords export default to make it the default export: 


export default function foo() {} // no semicolon! 
export default class Bar {} // no semicolon! 


You can also omit the name in this case. That makes default exports the only place where JavaScript 
has anonymous function declarations and anonymous class declarations: 


export default function () {} // no semicolon! 
export default class {} // no semicolon! 
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17.3.2.1.1 Why anonymous function declarations and not anonymous function expressions? 
When you look at the previous two lines of code, you'd expect the operands of export default 
to be expressions. They are only declarations for reasons of consistency: operands can be named 
declarations, interpreting their anonymous versions as expressions would be confusing (even more 
so than introducing new kinds of declarations). 


If you want the operands to be interpreted as expressions, you need to use parentheses: 


export default (function () (7); 
export default (class (7); 


17.3.2.2 Default export style 2: directly default-exporting values 
The values are produced via expressions: 


export default 'abc'; 

export default foo(); 

export default /^xyz$/; 

export default { no: false, yes: true }; 
export default 5 x 7; 


Each of these default exports has the following structure. 
export default «expression»; 
That is equivalent to: 


const __default__ = «expression»; 


export { __default__ as default }; // (A) 


The statement in line A is an export clause (which is explained in a later section). 


17.3.2.2.1 Why two default export styles? The second default export style was introduced 
because variable declarations can't be meaningfully turned into default exports if they declare 
multiple variables: 


export default const foo = 1, bar = 2, baz = 3; // not legal JavaScript! 


Which one of the three variables foo, bar and baz would be the default export? 


17.3.3 Imports are hoisted 


Module imports are hoisted (internally moved to the beginning of the current scope). Therefore, it 
doesn't matter where you mention them in a module and the following code works without any 
problems: 
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foo(); 
import { foo } from 'my_module'; 


17.3.4 Imports are read-only views on exports 


The imports of an ES6 modules are read-only views on the exported entities. That means that the 
connections to variables declared inside module bodies remain live, as demonstrated in the following 
code. 


//------ lib.js ------ 

export let counter = 3; 

export function incCounter() { 
counter++; 


pp === main.js -=-=-=--- 
import { counter, incCounter } from './lib'; 


// The imported value ‘counter’ is live 
console. log(counter); // 3 
incCounter(); 

console.log(counter); // 4 


How that works under the hood is explained in a later section. 
Imports as views have the following advantages: 
e They enable cyclic dependencies, even for unqualified imports (as explained in the next 
section). 
e Qualified and unqualified imports work the same (they are both indirections). 


e You can split code into multiple modules and it will continue to work (as long as you don't 
try to change the values of imports). 


17.3.5 Support for cyclic dependencies 


Two modules A and B are cyclically dependent’ on each other if both A (possibly indirectly/transi- 
tively) imports B and B imports A. If possible, cyclic dependencies should be avoided, they lead to 
A and B being tightly coupled — they can only be used and evolved together. 


Why support cyclic dependencies, then? Occasionally, you can’t get around them, which is why 
support for them is an important feature. A later section has more information. 


Let's see how CommonJS and ECMAScript 6 handle cyclic dependencies. 


"http://en.wikipedia.org/wiki/Circular_dependency 
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17.3.5.1 Cyclic dependencies in CommonjS 


The following CommonJS code correctly handles two modules a and b cyclically depending on each 
other. 


[1------ as... 

var b = require('b'); 

function foo() { 
b.bar(); 

} 


exports.foo = foo; 


/1------ b.js ------ 
var a = require('a'); // (1) 
function bar() { 
if (Math.random()) { 
a.foo(); // (11) 


} 


exports.bar = bar; 


If module a is imported first then, in line i, module b gets a’s exports object before the exports 
are added to it. Therefore, b cannot access a. foo in its top level, but that property exists once the 
execution of a is finished. If bar() is called afterwards then the method call in line ii works. 


As a general rule, keep in mind that with cyclic dependencies, you can’t access imports in the body 
of the module. That is inherent to the phenomenon and doesn’t change with ECMAScript 6 modules. 


The limitations of the CommonJS approach are: 


e Node.js-style single-value exports don’t work. There, you export single values instead of 
objects: 


module.exports = function () { =: }; 


If module a did that then module b’s variable a would not be updated once the assignment is 
made. It would continue to refer to the original exports object. 
e You can’t use named exports directly. That is, module b can’t import foo like this: 


var foo = require('a').foo; 


foo would simply be undefined. In other words, you have no choice but to refer to foo via 
a. foo. 


These limitations mean that both exporter and importers must be aware of cyclic dependencies and 
support them explicitly. 
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17.3.5.2 Cyclic dependencies in ECMAScript 6 


ES6 modules support cyclic dependencies automatically. That is, they do not have the two limitations 
of CommonJS modules that were mentioned in the previous section: default exports work, as do 
unqualified named imports (lines i and iii in the following example). Therefore, you can implement 
modules that cyclically depend on each other as follows. 


E aaa ajs as 
import {bar} from 'b'; // (1) 
export function foo() { 


bar(); // (11) 


| /------ b.js ------ 
import {foo} from 'a'; // (111) 
export function bar() { 
if (Math.random()) { 
foo(); // (iv) 
} 
} 


This code works, because, as explained in the previous section, imports are views on exports. That 
means that even unqualified imports (such as bar in line ii and foo in line iv) are indirections that 
refer to the original data. Thus, in the face of cyclic dependencies, it doesn’t matter whether you 
access a named export via an unqualified import or via its module: There is an indirection involved 
in either case and it always works. 


17.3.6 Module files are normal JavaScript files 
The following kinds of files all have the extension . js: 


1. ECMAScript 6 modules 

2. CommonJS modules (e.g. delivered via npm) 

3. AMD modules 

4. Script files (loaded from HTML files via <script src="file.js">) 


That is, all of these files are just “JavaScript files”. How they are interpreted depends on the context 
in which they are used. 


17.3.7 Be careful with ES6 transpilers 


ES6 transpilers such as Babel compile ES6 modules to ES5. Imports being views on exports is tricky 
to implement in plain JavaScript. But integrating legacy module systems is even harder. I therefore 
recommend to keep things simple and to be careful with the more exotic aspects of ES6 modules. 
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17.4 Importing and exporting in detail 


17.4.1 Importing styles 


ECMAScript 6 provides several styles of importing‘: 


e Default import: 


import localName from 'src/my_lib'; 


e Namespace import: imports the module as an object (with one property per named export). 


import * as my_lib from 'src/my_lib'; 


e Named imports: 
import { namel, name2 } from 'src/my_lib'; 
You can rename named imports: 


// Renaming: import 'namel” as 'localNamel” 
import { namel as localNamel, name2 } from 'src/my_lib'; 


e Empty import: only loads the module, doesn’t import anything. The first such import in a 
program executes the body of the module. 


import 'src/my_lib'; 


There are only two ways to combine these styles and the order in which they appear is fixed; the 
default export always comes first. 


e Combining a default import with a namespace import: 


import theDefault, * as my_lib from 'src/my_lib'; 


e Combining a default import with named imports 


import theDefault, { namel, name2 } from 'src/my_lib'; 


17.4.2 Exporting styles: inline versus clause 


There are two ways’ in which you can export things that are inside the current module. On one 
hand, you can mark declarations with the keyword export. 


*[Spec] Sect. “Imports” starts with grammar rules and continues with semantics. 
"http://www.ecma-international.org/ecma-262/6.0/#sec-exports 
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export var myVarl e 
export let myVar2 = +++; 
export const MY_CONST = +++; 


export function myFunc() { 


} 


export function» myGeneratorFunc() { 


} 


export class MyClass { 


The “operand” of a default export is an expression (including function expressions and class 
expressions). Examples: 


export default 123; 
export default function (x) { 
return x 
} 
export default x => x; 
export default class { 
constructor (x, y) { 
this.x = x; 
this.y = y; 


On the other hand, you can list everything you want to export at the end of the module (which is 
once again similar in style to the revealing module pattern). 


const MY_CONST = +++; 
function myFunc() { 


export { MY_CONST, myFunc 7; 


You can also export things under different names: 
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export { MY_CONST as FOO, myFunc }; 


17.4.3 Re-exporting 


Re-exporting means adding another module’s exports to those of the current module. You can either 
add all of the other module’s exports: 


export x from 'src/other_module'; 


Default exports are ignored* by export x. 


Or you can be more selective (optionally while renaming): 


export { foo, bar } from 'src/other_module'; 


// Renaming: export other_module’s foo as myFoo 
export { foo as myFoo, bar } from 'src/other_module' ; 


17.4.3.1 Making a re-export the default export 


The following statement makes the default export of another module foo the default export of the 
current module: 


export { default } from 'foo'; 


The following statement makes the named export myFunc of module foo the default export of the 
current module: 


export { myFunc as default } from 'foo'; 


17.4.4 All exporting styles 


ECMAScript 6 provides several styles of exporting’: 


e Re-exporting: 
— Re-export everything (except for the default export): 


*[Spec] The specification method GetExportedNames () collects the exports of a module. In step (7.d.i), a check prevents other modules’ default 
exports from being re-exported. 


*[Spec] Sect. “Exports” starts with grammar rules and continues with semantics. 
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export x from 'src/other_module'; 
— Re-export via a clause: 
export { foo as myFoo, bar } from 'src/other_module' ; 


e Exporting via a clause: 


export { MY_CONST as FOO, myFunc }; 


e Inline exports: 
— Variable declarations: 


export var foo; 
export let foo; 
export const foo; 


— Function declarations: 


export function myFunc() {} 
export function* myGenFunc() {} 


— Class declarations: 
export class MyClass() {} 


e Default export: 
— Function declarations (can be anonymous, but only here): 


export default function myFunc() {} 
export default function () {} 


export default function» myGenFunc() {} 
export default functionx () {} 


— Class declarations (can be anonymous, but only here): 
export default class MyClass() {} 
export default class () {} 

— Expressions: export values. Note the semicolons at the end. 


export default foo; 

export default 'Hello world!'; 
export default 3 x 7; 

export default (function () (7); 


17.4.5 Having both named exports and a default export in a 
module 


The following pattern is surprisingly common in JavaScript: A library is a single function, but 
additional services are provided via properties of that function. Examples include ¡Query and 
Underscore.js. The following is a sketch of Underscore as a CommonJS module: 
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[J] == underscore.js ------ 
var _ = function (obj) { 

}5 

var each = _.each = _.forEach = 


function (obj, iterator, context) { 


$5 


module.exports = _; 


//-----7 main.js ------ 
var _ = require('underscore'); 
var each = _.each; 


With ES6 glasses, the function _ is the default export, while each and forEach are named exports. 
As it turns out, you can actually have named exports and a default export at the same time. As an 
example, the previous CommonJS module, rewritten as an ES6 module, looks like this: 


pp ====== underscore.js ------ 
export default function (obj) { 


} 


export function each(obj, iterator, context) { 


} 


export { each as forEach }; 


y ===> main.js -=-=-=-=-- 
import _, { each } from 'underscore'; 


Note that the CommonJS version and the ECMAScript 6 version are only roughly similar. The latter 
has a flat structure, whereas the former is nested. 


For ES6 modules, I generally recommend to either only have a default export or only named exports 
in a single module. That is, you should not mix those different styles of exporting. 


17.4.5.1 The default export is just another named export 


The default export is actually just a named export with the special name default. That is, the 
following two statements are equivalent: 
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import { default as foo } from 'lib'; 
import foo from 'lib'; 


Similarly, the following two modules have the same default export: 


[ [=== modulel.js ------ 
export default function foo() {} // function declaration! 


fj- === module2.js ------ 


function foo() {} 
export { foo as default }; 


17.4.5.2 default: OK as export name, but not as variable name 


You can’t use reserved words (such as default and new) as variable names, but you can use them 
as names for exports (you can also use them as property names in ECMAScript 5). If you want to 
directly import such named exports, you have to rename them to proper variables names. 


That means that default can only appear on the left-hand side of a renaming import: 
import { default as foo } from 'some_module'; 

And it can only appear on the right-hand side of a renaming export: 

export { foo as default }; 

In re-exporting, both sides of the as are export names: 


// The following two statements are equivalent: 
export { default } from 'foo'; 
export { default as default } from 'foo'; 


export { myFunc as default } from 'foo'; 
export { default as otherFunc } from 'foo'; 


17.5 The ECMAScript 6 module loader API 


In addition to the declarative syntax for working with modules, there is also a programmatic API. 
It allows you to: 


e Programmatically work with modules 
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e Configure module loading 


O The module loader API is not part of the ES6 
standard 


It will be specified in a separate document, the “JavaScript Loader Standard”, that will 
be evolved more dynamically than the language specification. The repository for that 
document” states: 


[The JavaScript Loader Standard] consolidates work on the ECMAScript 
module loading semantics with the integration points of Web browsers, as 
well as Node.js. 


A The module loader API is work in progress 


As you can see in the repository of the JavaScript Loader Standard", the module loader 
API is still work in progress. Everything you read about it in this book is tentative. To get 
an impression of what the API may look like, you can take a look at the ES6 Module Loader 
Polyfill** on GitHub. 


17.5.1 Loaders 


Loaders handle resolving module specifiers (the string IDs at the end of import-from), loading 
modules, etc. Their constructor is Reflect. Loader. Each platform keeps a default instance in the 
global variable System (the system loader), which implements its specific style of module loading. 


17.5.2 Loader method: importing modules 


You can programmatically import a module, via an API based on Promises: 


*°https://github.com/whatwg/loader/ 
“https://github.com/whatwg/loader/ 
“https://github.com/ModuleLoader/es6-module-loader 
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System. import ('some_module') 
.then(some_module => { 
// Use some_module 


+) 


.catch(error => { 
$; 
System. import () enables you to: 


e Use modules inside <script> elements (where module syntax is not supported, consult the 
section on modules vs. scripts for details). 
e Load modules conditionally. 


System. import() retrieves a single module, you can use Promise.all() to import several 
modules: 


Promise.all( 
['module1', 'module2', 'module3'] 
.map(x => System.import(x))) 

.then(([modulel, module2, module3]) => { 
// Use modulel, module2, module3 

$; 


17.5.3 More loader methods 


Loaders have more methods. Three important ones are: 


e System.module(source, options?) 
evaluates the JavaScript code in source to a module (which is delivered asynchronously via 
a Promise). 
e System.set(name, module) 
is for registering a module (e.g. one you have created via System. module ()). 
e System.define(name, source, options?) 
both evaluates the module code in source and registers the result. 


17.5.4 Configuring module loading 


The module loader API will have various hooks for configuring the loading process. Use cases 
include: 
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1. Lint modules on import (e.g. via JSLint or JSHint). 

2. Automatically translate modules on import (they could contain CoffeeScript or TypeScript 
code). 

3. Use legacy modules (AMD, Node.js). 


Configurable module loading is an area where Node.js and CommonJS are limited. 


17.6 Using ES6 modules in browsers 


Let's look at how ES6 modules are supported in browsers. 


A Support for ES6 modules in browsers is work 
in progress 


Similarly to module loading, other aspects of support for modules in browsers are still being 
worked on. Everything you read here may change. 


17.6.1 Browsers: asynchronous modules versus synchronous 
scripts 


In browsers, there are two different kinds of entities: scripts and modules. They have slightly 
different syntax and work differently. 


This is an overview of the differences, details are explained later: 


Scripts Modules 
HTML element <script> <script type="module"> 
Top-level variables are global local to module 
Value of this at top level window undefined 
Executed synchronously asynchronously 
Import modules declaratively (import syntax) no yes 
Import modules via Promise-based loader API yes yes 
File extension .js .js 


17.6.1.1 Scripts 


Scripts are the traditional browser way to embed JavaScript and to refer to external JavaScript files. 
Scripts have an internet media type” that is used as: 


http://en.wikipedia.org/wiki/Internet_media_type 
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e The content type of JavaScript files delivered via a web server. 

e The value of the attribute type of <script> elements. Note that for HTML5, the recom- 
mendation is to omit the type attribute in <script> elements if they contain or refer to 
JavaScript. 


The following are the most important values: 


e text/javascript: is a legacy value and used as the default if you omit the type attribute 
in a script tag. It is the safest choice** for Internet Explorer 8 and earlier. 


e application/javascript: is recommended” for current browsers. 


Scripts are normally loaded or executed synchronously. The JavaScript thread stops until the code 
has been loaded or executed. 


17.6.1.2 Modules 


To be in line with JavaScript’s usual run-to-completion semantics, the body of a module must be 
executed without interruption. That leaves two options for importing modules: 


1. Load modules synchronously, while the body is executed. That is what Node.js does. 

2. Load all modules asynchronously, before the body is executed. That is how AMD modules are 
handled. It is the best option for browsers, because modules are loaded over the internet and 
execution doesn’t have to pause while they are. As an added benefit, this approach allows one 
to load multiple modules in parallel. 


ECMAScript 6 gives you the best of both worlds: The synchronous syntax of Node.js plus the 
asynchronous loading of AMD. To make both possible, ES6 modules are syntactically less flexible 
than Node.js modules: Imports and exports must happen at the top level. That means that they 
can’t be conditional, either. This restriction allows an ES6 module loader to analyze statically what 
modules are imported by a module and load them before executing its body. 


The synchronous nature of scripts prevents them from becoming modules. Scripts cannot even 
import modules declaratively (you have to use the programmatic module loader API if you want to 
do so). 


Modules can be used from browsers via a new variant of the <script> element that is completely 
asynchronous: 


“http://stackoverflow.com/questions/359895/what-are-the-most-likely-causes-of-javascript-errors-in-ie8/7035904703590 
http://tools.ietf.org/html/rfc4329#section-7 
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<script type="module"> 
import $ from 'lib/jquery'; 
var x = 123; 


// The current scope is not global 
console.log('S' in window); // false 
console.log('x' in window); // false 


// ‘this’ still refers to the global object 
console.log(this === window); // true 
</script> 


As you can see, the element has its own scope and variables “inside” it are local to that scope. Note 
that module code is implicitly in strict mode. This is great news — no more 'use strict'. 


Similar to normal <script> elements, <script type="module"> can also be used to load external 
modules. For example, the following tag starts a web application via a main module (the attribute 
name import is my invention, it isn't yet clear what name will be used). 


<script type="module" import="impl/main"></script> 


The advantage of supporting modules in HTML via a custom <script> type is that it is easy to 
bring that support to older engines via a polyfill (a library). There may or may not eventually be a 
dedicated element for modules (e.g. <module>). 


17.6.2 Bundling 


Modern web applications consist of many, often small, modules. Loading those modules over HTTP 
impacts performance negatively, because a separate request is needed for each. Therefore, bundling 
multiple modules as a single file has a long tradition in the web development world. Current 
approaches are complex and error-prone and only work for JavaScript. There are two solutions: 


e HTTP/2: will allow multiple requests per TCP connection, which makes bundling unneces- 
sary. You can then incrementally update your application, because if a single module changes, 
browsers don't have to download the complete bundle, again. 

e Packages: Additionally, the W3C Technical Architecture Group is working on a standard for 
“Packaging on the Web*”. The idea is to put a whole directory into a package (think ZIP file, 
but a different format). Then this package URL: 


“https://w3ctag.github.io/packaging-on-the-web/ 
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http: //example.org/downloads/editor.pack#ur l=/root. html; fragment=colophon 


... is equivalent to the following normal URL, if the package were unpacked into the root of 
the web server: 


http://example.org/root.html+colophon 


Browsers have to make sure that once you are inside a package, relative URLs work as 
expected. 


Ea Sources of this section 


e “Modules: Status Update”””, slides by David Herman. 


18» 


e “Modules vs Scripts**”, an email by David Herman. 


17.7 Details: imports as views on exports 


lap) The code in this section is available on GitHub”. 


Imports work differently in CommonJS and ES6: 


e In CommonJS, imports are copies of exported values. 
e In ES6, imports are live read-only views on exported values. 


The following sections explain what that means. 


17.7.1 In CommonJS, imports are copies of exported values 


With CommonJS (Node.js) modules, things work in relatively familiar ways. 


If you import a value into a variable, the value is copied twice: once when it is exported (line A) and 
once it is imported (line B). 


https://github.com/rwaldron/tc39-notes/blob/master/es6/2013-09/modules.pdf 
“Shttps://mail.mozilla.org/pipermail/es-discuss/2013-November/034869.html 


“https://github.com/rauschma/imports-are-views-demo 
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{Į ------ Lab: Js ===828 

var counter = 3; 

function incCounter() { 
counter++; 

} 

module.exports = { 
counter: counter, // (A) 
incCounter: incCounter, 


JJ === maini. js ------ 
var counter = require('./lib').counter; // (B) 
var incCounter = require('./lib').incCounter; 


// The imported value is a (disconnected) copy of a copy 
console. log(counter); // 3 

incCounter () ; 

console. lLog(counter); // 3 


// The imported value can be changed 
counter++; 
console. log(counter); // 4 


If you access the value via the exports object, it is still copied once, on export: 


{[==s=== main2.js ------ 
var lib = require('./lib'); 


// The imported value is a (disconnected) copy 
console.log(lib.counter); // 3 
lib.incCounter(); 

console.log(lib.counter); // 3 


// The imported value can be changed 
lib.counter++; 
console.log(lib.counter); // 4 


17.7.2 In ES6, imports are live read-only views on exported values 


In contrast to CommonJS, imports are views on exported values. In other words, every import is a 
live connection to the exported data. Imports are read-only: 
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e Unqualified imports (import x from 'foo') are like const-declared variables. 
e The properties of a module object foo (import * as foo from 'foo') are like the properties 
of a frozen object”. 


The following code demonstrates how imports are like views: 


//------ lib.js ------ 

export let counter = 3; 

export function incCounter() { 
counter++; 


| p====== mami. Ss =*=*sS 
import { counter, incCounter } from './lib'; 


// The imported value 'counter' is live 
console. lLog(counter); // 3 

incCounter () ; 

console. log(counter); // 4 


// The imported value can’t be changed 
countert++; // TypeError 


If you import the module object via the asterisk (*), you get the same results: 


[J] === main227s +=====3= 
import x as lib from './lib'; 


// The imported value `counter` is live 
console.log(lib.counter); // 3 
lib.incCounter(); 
console.log(lib.counter); // 4 


// The imported value can’t be changed 
lib.counter++; // TypeError 


Why introduce such a relatively complicated mechanism that deviates from established practices? 


e Cyclic dependencies: The main advantage is that it supports cyclic dependencies even for 
unqualified imports. 


*°http://speakingjs.com/es5/ch17.html#freezing_objects 
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e Qualified and unqualified imports work the same. In CommonjJS, they don't: a qualified import 
provides direct access to a property of a module’s export object, an unqualified import is a copy 
of it. 

e You can split code into multiple modules and it will continue to work (as long as you don't 
try to change the values of imports). 


Note that while you can't change the values of imports, you can change the objects that they are 
referring to. For example: 


| [===-== tib, Js ====== 
export let obj = {}; 


pl ====== main.js -=-=-=-=-- 
import { obj } from './lib'; 


obj.prop = 123; // OK 
obj = {}; // TypeError 


17.7.3 Implementing views 


How do imports work as views of exports under the hood? Exports are managed via the data 
structure export entry. All export entries (except those for re-exports) have the following two names: 


e Local name: is the name under which the export is stored inside the module. 
e Export name: is the name that importing modules need to use to access the export. 


After you have imported an entity, that entity is always accessed via a pointer that has the two 
components module and local name. In other words, that pointer refers to a binding (the storage 
space of a variable) inside a module. 


Let’s examine the export names and local names created by various kinds of exporting. The following 
table (adapted from the ES6 spec”*) gives an overview, subsequent sections have more details. 


Statement Local name Export name 
export {v}; 'v' ty" 

export {v as xP; 'v' pá 

export let v = 123; y! y! 

export function f() {} Ef! Et 

export default function f() {} 'f' 'default' 
export default function () {} 'xdefaultx' 'default' 
export default 123; 'xdefaultx' 'default' 


**http://www.ecma-international.org/ecma-262/6.0/#table-42 
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17.7.3.1 Export clause 


function foo() {} 
export { foo }; 


e Local name: foo 
e Export name: foo 


function foo() {} 
export { foo as bar }; 


e Local name: foo 
+ Export name: bar 


17.7.3.2 Inline exports 


This is an inline export: 
export function foo() {} 
It is equivalent to the following code: 


function foo() {} 
export { foo }; 


Therefore, we have the following names: 


e Local name: foo 
e Export name: foo 


17.7.3.3 Default exports 


There are two kinds of default exports: 
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e Default exports of hoistable declarations (function declarations, generator function declara- 
tions) and class declarations are similar to normal inline exports in that named local entities 


are created and tagged. 


e All other default exports are about exporting the results of expressions. 


17.7.3.3.1 Default-exporting expressions The following code default-exports the result of the 


expression 123: 
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export default 123; 
It is equivalent to: 


const *defaultx = 123; // *notx* legal JavaScript 
export { xdefault* as default }; 


If you default-export an expression, you get: 


e Local name: *xdefaultx 
e Export name: default 


The local name was chosen so that it wouldn’t clash with any other local name. 


Note that a default export still leads to a binding being created. But, due to default not being a 
legal identifier, you can’t access that binding from inside the module. 


17.7.3.3.2 Default-exporting hoistable declarations and class declarations The following 
code default-exports a function declaration: 


export default function foo() {} 
It is equivalent to: 


function foo() {} 
export { foo as default }; 


The names are: 


e Local name: foo 
+ Export name: default 


That means that you can change the value of the default export from within the module, by assigning 
a different value to foo. 


(Only) for default exports, you can also omit the name of a function declaration: 
export default function () {} 


That is equivalent to: 


Modules 272 


function xdefault*() {} // *xnot*x legal JavaScript 
export { xdefault* as default }; 


The names are: 


e Local name: *xdefaultx 
e Export name: default 


Default-exporting generator declarations and class declarations works similarly to default-exporting 
function declarations. 


17.7.4 Imports as views in the spec 


This section gives pointers into the ECMAScript 2015 (ES6) language specification. 


Managing imports: 


e CreatelmportBinding()” creates local bindings for imports. 

e GetBindingValue()” is used to access them. 

e ModuleDeclarationInstantiation()* sets up the environment of a module (compare: Function- 
DeclarationInstantiation()”, BlockDeclarationInstantiation()”). 


The export names and local names created by the various kinds of exports are shown in table 42” 
in the section “Source Text Module Records”*”. The section “Static Semantics: ExportEntries”” has 
more details. You can see that export entries are set up statically (before evaluating the module), 
evaluating export statements is described in the section “Runtime Semantics: Evaluation*”., 


17.8 Design goals for ES6 modules 


If you want to make sense of ECMAScript 6 modules, it helps to understand what goals influenced 
their design. The major ones are: 


e Default exports are favored 


224 
23), 
24), 
25), 


tp://www.ecma-international.org/ecma-262/6.0/*sec-createimportbinding 
t 
t 
t 
25h ttp://www.ecma-international.org/ecma-262/6.0/+sec-blockdeclarationinstantiation 
t] 
t 
t 
t 


p://www.ecma-international.org/ecma-262/6.0/#sec-module-environment-records- getbindingvalue-n-s 
p://www.ecma-international.org/ecma-262/6.0/#sec-moduledeclarationinstantiation 
p://www.ecma-international.org/ecma-262/6.0/*sec-functiondeclarationinstantiation 


27), 
28), 
29), 
30), 


p://www.ecma-international.org/ecma-262/6.0/#table-42 
p://www.ecma-international.org/ecma-262/6.0/#sec-source-text-module- records 
p://www.ecma-international.org/ecma- 262/6.0/#sec-exports-static- semantics- exportentries 


p://www.ecma-international.org/ecma-262/6.0/#sec-exports-runtime-semantics- evaluation 
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e Static module structure 
e Support for both synchronous and asynchronous loading 
e Support for cyclic dependencies between modules 


The following subsections explain these goals. 


17.8.1 Default exports are favored 


es 3 


The module syntax suggesting that the default export “is” the module may seem a bit strange, but it 
makes sense if you consider that one major design goal was to make default exports as convenient 
as possible. Quoting David Herman”: 


ECMAScript 6 favors the single/default export style, and gives the sweetest syntax to 
importing the default. Importing named exports can and even should be slightly less 
concise. 


17.8.2 Static module structure 


In current JavaScript module systems, you have to execute the code in order to find out what the 
imports and exports are. That is the main reason why ECMAScript 6 breaks with those systems: 
by building the module system into the language, you can syntactically enforce a static module 
structure. Let's first examine what that means and then what benefits it brings. 


A module’s structure being static means that you can determine imports and exports at compile time 
(statically) - you only have to look at the source code, you don't have to execute it. The following 
are two examples of how CommonJS modules can make that impossible. In the first example, you 
have to run the code to find out what it imports: 


var my_lib; 
if (Math.random()) { 

my_lib = require('foo'); 
} else { 

my_lib = require('bar'); 


In the second example, you have to run the code to find out what it exports: 


**http://esdiscuss.org/topic/moduleimport#content-0 
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if (Math.random()) { 
exports.baz = **+*; 


} 


ECMAScript 6 gives you less flexibility, it forces you to be static. As a result, you get several benefits, 
which are described next. 


17.8.2.1 Benefit 1: faster lookup 


If you require a library in CommonJS, you get back an object: 


var lib = require('lib'); 
lib.someFunc(); // property lookup 


Thus, accessing a named export via lib. someFunc means you have to do a property lookup, which 
is slow, because it is dynamic. 


In contrast, if you import a library in ES6, you statically know its contents and can optimize accesses: 


import x as lib from 'lib'; 
lib.someFunc(); // statically resolved 


17.8.2.2 Benefit 2: variable checking 


With a static module structure, you always statically know which variables are visible at any location 
inside the module: 


e Global variables: increasingly, the only completely global variables will come from the 
language proper. Everything else will come from modules (including functionality from the 
standard library and the browser). That is, you statically know all global variables. 

e Module imports: You statically know those, too. 

e Module-local variables: can be determined by statically examining the module. 


This helps tremendously with checking whether a given identifier has been spelled properly. This 
kind of check is a popular feature of linters such as JSLint and JSHint; in ECMAScript 6, most of it 
can be performed by JavaScript engines. 


Additionally, any access of named imports (such as Lib. foo) can also be checked statically. 


17.8.2.3 Benefit 3: ready for macros 


Macros are still on the roadmap for JavaScript’s future. If a JavaScript engine supports macros, you 
can add new syntax to it via a library. Sweet.js*’ is an experimental macro system for JavaScript. 
The following is an example from the Sweet.js website: a macro for classes. 


**http://sweetjs.org 
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// Define the macro 
macro class { 
rule { 
SclassName { 
constructor $cparams $cbody 
$(Smname $mparams $mbody) 
} 
} = { 
function $className $cparams $cbody 
$($className.prototype.$mname 
= function $mname $mparams $mbody; ) 


// Use the macro 
class Person { 
constructor(name) { 
this.name = name; 


} 
say(msg) { 

console. log(this.name + " says: " + msg); 
} 


} 
var bob = new Person("Bob"); 
bob.say("Macros are sweet!"); 


For macros, a JavaScript engine performs a preprocessing step before compilation: If a sequence 
of tokens in the token stream produced by the parser matches the pattern part of the macro, it is 
replaced by tokens generated via the body of macro. The preprocessing step only works if you are 
able to statically find macro definitions. Therefore, if you want to import macros via modules then 
they must have a static structure. 


17.8.2.4 Benefit 4: ready for types 


Static type checking imposes constraints similar to macros: it can only be done if type definitions can 
be found statically. Again, types can only be imported from modules if they have a static structure. 


Types are appealing because they enable statically typed fast dialects of JavaScript in which 
performance-critical code can be written. One such dialect is Low-Level JavaScript? (LLJS). It 
currently compiles to asm.js*. 


http://lljs.org 
*4http://www.2ality.com/2013/02/asm-js.html 
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17.8.2.5 Benefit 5: supporting other languages 


If you want to support compiling languages with macros and static types to JavaScript then 
JavaScript’s modules should have a static structure, for the reasons mentioned in the previous two 
sections. 


17.8.2.6 Source of this section 
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e “Static module resolution?”” by David Herman 


17.8.3 Support for both synchronous and asynchronous loading 


ECMAScript 6 modules must work independently of whether the engine loads modules syn- 
chronously (e.g. on servers) or asynchronously (e.g. in browsers). Its syntax is well suited for 
synchronous loading, asynchronous loading is enabled by its static structure: Because you can 
statically determine all imports, you can load them before evaluating the body of the module (in 
a manner reminiscent of AMD modules). 


17.8.4 Support for cyclic dependencies between modules 


Support for cyclic dependencies was a key goal for ES6 modules. Here is why: 


Cyclic dependencies are not inherently evil. Especially for objects, you sometimes even want this 
kind of dependency. For example, in some trees (such as DOM documents), parents refer to children 
and children refer back to parents. In libraries, you can usually avoid cyclic dependencies via careful 
design. In a large system, though, they can happen, especially during refactoring. Then it is very 
useful if a module system supports them, because the system doesn’t break while you are refactoring. 


The Node.js documentation acknowledges the importance of cyclic dependencies** and Rob Sayre 
provides additional evidence”: 


Data point: I once implemented a system like [ECMAScript 6 modules] for Firefox. I 
got asked”* for cyclic dependency support 3 weeks after shipping. 


That system that Alex Fritze invented and I worked on is not perfect, and the syntax isn’t 
very pretty. But it’s still getting used?” 7 years later, so it must have gotten something 
right. 


http://calculist.org/blog/2012/06/29/static-module-resolution/ 
"http://nodejs.org/api/modules.html*modules_cycles 
37https://mail.mozilla.org/pipermail/es-discuss/2014-July/038250.html 
*8https://bugzilla.mozilla.org/show_bug.cgi?id=384168#c7 
>°https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Using 


Modules 277 


17.9 FAQ: modules 


17.9.1 Can l use a variable to specify from which module | want to 
import? 


The import statement is completely static: its module specifier is always fixed. If you want to 
dynamically determine what module to load, you need to use the programmatic loader API: 


let moduleSpecifier = 'module_' + Math.random() ; 
System. import (moduleSpeci fier) 
.then(the_module => { 
// Use the_module 
}) 


17.9.2 Can | import a module conditionally or on demand? 


Import statements must always be at the top level of modules. That means that you can’t nest them 
inside if statements, functions, etc. Therefore, you have to use the programmatic loader API if you 
want to load a module conditionally or on demand: 


if (Math.random()) { 
System. import('some_module') 
.then(some_module => { 
// Use some_module 
}) 
} 


17.9.3 Can I use destructuring in an import statement? 


No you can’t. The import statement only looks a little bit like destructuring, but is completely 
different (static, imports are views, etc.). 


Therefore, you can’t do something like this in an ES6 module: 


var bar = require('some_module').foo.bar; 
q ; 


17.9.4 Are named exports necessary? Why not default-export 
objects? 
You may be wondering — why do we need named exports if we could simply default-export objects 


(like one does in CommonJS)? The answer is that you can't enforce a static structure via objects and 
lose all of the associated advantages (which are explained in this chapter). 
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17.9.5 Can | eval () modules? 


No, you can’t. Modules are too high-level a construct for eval(). The module loader API provides 
the means for creating modules from strings. Syntactically, eval () accepts scripts, not modules. 


17.10 Benefits of ECMAScript 6 modules 


At first glance, having modules built into ECMAScript 6 may seem like a boring feature — after all, 
we already have several good module systems. But ECMAScript 6 modules have features that you 
can't add via a library, such as a more compact syntax and a static module structure (which helps 
with optimizations, static checking and more). They will also — hopefully — end the fragmentation 
between the currently dominant standards CommonJS and AMD. 


Having a single, native standard for modules means: 


e No more UMD (Universal Module Definition*”): UMD is a name for patterns that enable the 
same file to be used by several module systems (e.g. both CommonJS and AMD). Once ES6 is 
the only module standard, UMD becomes obsolete. 

e New browser APIs become modules instead of global variables or properties of navigator. 

e No more objects-as-namespaces: Objects such as Math and JSON serve as namespaces for 
functions in ECMAScript 5. In the future, such functionality can be provided via modules. 


17.11 Further reading 


e CommonJS vs. ES6: “JavaScript Modules**” (by Yehuda Katz*) is a quick intro to ECMAScript 
6 modules. Especially interesting is a second page* where CommonJS modules are shown side 
by side with their ECMAScript 6 versions. 


“https://github.com/umdjs/umd 
“*http://jsmodules.io/ 
“2https://github.com/wycats/jsmodules 
“Shttp://jsmodules.io/cjs.html 


IV Collections 


18. New Array features 


This chapter explains new Array features in ES6. 


18.1 Overview 


New static Array methods: 


e Array. from(arrayLike, mapFunc?, thisArg?) 
e Array.of(...items) 


New Array.prototype methods: 


e Iterating: 
— Array.prototype.entries() 
— Array.prototype.keys() 
— Array.prototype.values() 
e Searching for elements: 
— Array.prototype.find(predicate, thisArg?) 
— Array.prototype.findIndex (predicate, thisArg?) 
e Array.prototype.copyWithin(target, start, end=this. length) 
e Array.prototype.fill(value, start=0, end=this. length) 


18.2 New static Array methods 
The object Array has new methods. 
18.2.1 Array. from(arrayLike, mapFunc?, thisArg?) 
Array. from()’s basic functionality is to convert two kinds of objects to Arrays: 
e Array-like objects’, which have a property length and indexed elements. Examples include 
the results of DOM operations such as document .getElementsByClassName(). 


e Iterable objects, whose contents can be retrieved one element at a time. Arrays are iterable, 
as are ECMAScript’s new data structures Map and Set. 


The following code is an example of converting an Array-like object to an Array: 


*http://speakingjs.com/es5/ch18.html#_pitfall_array_like_objects 
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let Lis = document .querySelectorAll('ul.fancy li'); 
Array.from(lis).forEach(function (li) { 
console. log (node) ; 


}); 


The result of querySelectorAll() is not an Array and does not have a forEach() method, which 
is why we need to convert it to an Array before we can use that method. 


18.2.1.1 Mapping via Array.from() 


Array .from() is also a convenient alternative to using map() generically’: 
let spans = document .querySelectorAll('span.name'); 


// map(), generically: 
let namesl = Array.prototype.map.call(spans, s => s.textContent) ; 


// Array.from(): 
let names2 = Array.from(spans, s => s.textContent) ; 


In this example, the result of document. querySelectorALl() is again an Array-like object, not 
an Array, which is why we couldn’t invoke map() on it. Previously, we converted the Array-like 
object to an Array in order to call forEach(). Here, we skipped that intermediate step via a generic 
method call and via the two-parameter version of Array.from(). 


18.2.1.2 Holes 


Array .from() ignores holes in Arrays, it treats them as if they were undefined elements: 


> Array.from([0,,2]) 
[ 0, undefined, 2 ] 


That means that you can use Array. from() to create and fill an Array: 


Array.from(new Array(5), () => 'a') 
tar; es 5 "ay a la" ] 
Array.from(new Array(5), (x,1) => 1) 
0, 1, 2, 3, 4 ] 


aie Vas WV 


If you want to fill an Array with a fixed value (first one of the previous two examples) then 
Array.prototype.fill() (see below) is a better choice. 


*http://speakingjs.com/es5/ch17.html#generic_method 
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18.2.1.3 from() in subclasses of Array 


Another use case for Array. from() is to convert an Array-like or iterable object to an instance of 
a subclass of Array. For example, if you create a subclass MyArray of Array and want to convert 
such an object to an instance of MyArray, you simply use MyArray.from(). The reason that that 
works is because constructors inherit from each other in ECMAScript 6 (a super-constructor is the 
prototype of its sub-constructors). 


class MyArray extends Array { 


} 
let instanceOfMyArray = MyArray.from(anIterable) ; 


You can also combine this functionality with mapping, to get a map operation where you control 
the result’s constructor: 


// from() - determine the result’s constructor via the receiver 
// (in this case, MyArray) 
let instanceOfMyArray = MyArray.from([1, 2, 3], x => x * x); 


// map(): the result is always an instance of Array 
let instanceOfArray = [1, 2, 3].map(x => x * x); 


18.2.2 Array.of(...items) 


Array.of(item_0, item_1, -**-*) creates an Array whose elements are item_0, item_1, etc. 


18.2.2.1 Array.of() as an Array literal for subclasses of Array 


If you want to turn several values into an Array, you should always use an Array literal, especially 
since the Array constructor doesn’t work properly if there is a single value that is a number (more 
information’ on this quirk): 


> new Array(3, 11, 8) 

[ 3, 11, 8] 

> new Array(3) 

[ ? , ,] 

> new Array(3.1) 

RangeError: Invalid array length 


But how are you supposed to turn values into an instance of a sub-constructor of Array then? This is 
where Array .of () helps (remember that sub-constructors of Array inherit all of Array’s methods, 
including of ()). 


*http://speakingjs.com/es5/ch18.html#array_constructor 
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class MyArray extends Array { 


} 
console.log(MyArray.of(3, 11, 8) instanceof MyArray); // true 
console.log(MyArray.of(3).length === 1); // true 


18.3 New Array.prototype methods 


Several new methods are available for Array instances. 


18.3.1 Iterating over Arrays 


The following methods help with iterating over Arrays: 


e Array.prototype.entries() 
e Array.prototype.keys() 
e Array.prototype.values() 


The result of each of the aforementioned methods is a sequence of values, but they are not returned 
as an Array; they are revealed one by one, via an iterator. Let's look at an example. I’m using 
Array.from() to put the iterators’ contents into Arrays: 


> Array.from(['a', 'b'].keys()) 
[0,1] 

> Array.from(['a', 'b'].values()) 
[ ur hae 19 ] 

> Array.from(['a', 'b'].entries()) 
[ [ 0, 'a' 1, 

[ 1, 'b' ] ] 


I could have also used the spread operator (. . .) to convert iterators to Arrays: 


> [...['a', 'b'].keys()] 
[ 0, 1] 


18.3.1.1p 


airs]Iterating over [index, element] pairs 


You can combine entries() with ECMAScript 6’s for-of loop and destructuring to conveniently 
iterate over [index, element] pairs: 
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for (let [index, elem] of ['a', 'b'].entries()) £ 
console.log(index, elem); 


18.3.2 Searching for Array elements 


Array.prototype.find(predicate, thisArg?) 
Returns the first Array element for which the callback predicate returns true. If there is no such 
element, it returns undefined. Example: 


> [6, -5, 8].find(x => x < 0) 
=5 

> [6, 5, 8].find(x => x < 0) 
undefined 


Array.prototype.findIndex (predicate, thisArg?) 
Returns the index of the first element for which the callback predicate returns true. If there is no 
such element, it returns -1. Example: 


> [6, -5, 8].findIndex(x => x < 0) 
1 
> [6, 5, 8].findIndex(x => x < 0) 
=I 


The full signature of the callback predicate is: 
predicate(element, index, array) 


18.3.2.1 findIndex() treats holes as undefined elements 


findIndex() treats holes as undefined elements (with find(), you wouldn’t be able to tell 
whether or not it does, because it returns undefined if it can’t find anything): 


> ['a',,'c'].findIndex(x => x === undefined) 
1 


18.3.2.2 Finding nan via findIndex() 


A well-known limitation* of Array.prototype.index0f () is that it can’t find NaN, because it 
searches for elements via ===: 


“http://speakingjs.com/es5/ch18.html#_searching_for_values_nondestructive 
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> [NaN].index0f (NaN) 
=1 


With findIndex(), you can use Object. is() (explained in the chapter on OOP) and will have no 
such problem: 


> [NaN].findIndex(y => Object.is(NaN, y)) 
0 


You can also adopt a more general approach, by creating a helper function elemIs(): 


> function elemIs(x) { return Object.is.bind(Object, x) } 
> [NaN]. findIndex(elemIs (NaN) ) 
0 


18.3.3 Array.prototype.copyWithin() 


The signature of this method is: 


Array.prototype.copyWithin(target : number, start : number, end = this.length) :\ 
This 


It copies the elements whose indices are in the range [start,end) to index target and subsequent 
indices. If the two index ranges overlap, care is taken that all source elements are copied before they 
are overwritten. 


Example: 


let arr = [0,1,2,3]; 
arr.copyWithin(2, 0, 2) 
0, 1, 0, 1 ] 


os Vo Vv Vv 


18.3.4 Array.prototype. fill() 


The signature of this method is: 
Array.prototype.fill(value : any, start=0, end=this.length) : This 


It fills an Array with the given value: 
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let arr = ['a', 'b', 'c']; 
arr.fill(7) 

7, 7, 7 ] 

arr 

Ti fy T] 
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Holes get no special treatment: 


> new Array(3).fi11(7) 
[7,7,7] 


Optionally, you can restrict where the filling starts and ends: 


> ['a', 'b', 'c'].fill(7, 1, 2) 
Nana ES Ver ] 
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19. Maps and Sets 


Among others, the following four data structures are new in ECMAScript 6: Map, WeakMap, Set and 
WeakSet. This chapter explains how they work. 


19.1 Overview 


19.1.1 Maps 


The keys of a Map can be arbitrary values: 


> let map = new Map(); // create an empty Map 
> const KEY = {}; 


> map.set(KEY, 123); 
> map.get (KEY) 

123 

> map.has (KEY) 

true 

> map.delete(KEY) ; 
true 

> map.has (KEY) 

false 


You can use an Array (or any iterable) with [key, value] pairs to set up the initial data in the Map: 
let map = new Map([ 

[ 1, 'one' ], 

[ 2, 'two' ], 

[ 3, 'three' ], // trailing comma is ignored 


]); 


19.1.2 Sets 


A Set is a collection of unique elements: 
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let arr = [5, 1, 5, 7, 7, 5]; 
let unique = [...new Set(arr)]; // [ 5, 1, 7 ] 


As you can see, you can initialize a Set with elements if you hand the constructor an iterable (arr 
in the example) over those elements. 


19.1.3 WeakMaps 


A WeakMap is a Map that doesn't prevent its keys from being garbage-collected. That means that 
you can associate private data with objects without having to worry about memory leaks: 


let _counter = new WeakMap() ; 
let _action = new WeakMap() ; 
class Countdown { 
constructor (counter, action) { 
_counter.set(this, counter); 
_action.set(this, action); 


} 

dec() { 
let counter = _counter.get(this); 
if (counter < 1) return; 
counter--; 
_counter.set(this, counter); 
if (counter === 0) { 

_action.get(this)(); 

} 

} 


19.2 Map 


JavaScript has always had a very spartan standard library. Sorely missing was a data structure for 
mapping values to values. The best you can get in ECMAScript 5 is a Map from strings to arbitrary 
values, by abusing objects. Even then there are several pitfalls’ that can trip you up. 


The Map data structure in ECMAScript 6 lets you use arbitrary values as keys and is highly welcome. 


19.2.1 Basic operations 


Working with single entries: 


*http:/ /speakingjs.com/es5/ch17.html#_pitfalls_using_an_object_as_a_map 
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> let map = new Map(); 


> map.set( "fool, 123); 
> map.get('foo') 
123 


> map.has('foo') 
true 

> map.delete('foo') 
true 

> map.has('foo') 
false 


Determining the size of a Map and clearing it: 


> let map = new Map(); 
> map.set('foo', true); 
> map.set('bar', false); 


map.size 


map.clear(); 
map.size 


OQvvnNn yv 


19.2.2 Setting up a Map 
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You can set up a Map via an iterable over key-value “pairs” (Arrays with 2 elements). One possibility 


is to use an Array (which is iterable): 


let map = new Map([ 
[ 1, 'one' ], 
[ 2, "two" J; 


[ 3, 'three' ], // trailing comma is ignored 


]); 


Alternatively, the set () method is chainable: 


Maps and Sets 290 


let map = new Map() 
.set(1, 'one') 
.set(2, 'two') 
.set(3, 'three'); 


19.2.3 Keys 


Any value can be a key, even an object: 


let map = new Map(); 


const KEY1 = (7; 
map.set(KEY1, 'hello'); 
console.log(map.get(KEY1)); // hello 


const KEY2 = (7; 


map.set(KEY2, 'world'); 
console. lLog(map.get(KEY2)); // world 


19.2.3.1 What keys are considered equal? 


Most Map operations need to check whether a value is equal to one of the keys. They do so via the 


internal operation SameValueZero’, which works like ===, but considers NaN to be equal to itself. 
Let's first see how === handles NaN: 

> NaN === NaN 

false 


Conversely, you can use NaN as a key in Maps, just like any other value: 


> let map = new Map(); 


> map.set(NaN, 123); 
> map.get (NaN) 
123 


Like ===, -0 and +0 are considered the same value. That is normally the best way to handle the two 
zeros (details are explained in “Speaking JavaScript”). 


*http://www.ecma-international.org/ecma-262/6.0/#sec-samevaluezero 
*http://speakingjs.com/es5/ch11.html#two_zeros 
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> map.set(-0, 123); 
> map.get(+0) 
123 


Different objects are always considered different. That is something that can't be configured (yet), 
as explained later, in the FAQ. 


> new Map().set({}, 1).set({}, 2).size 
2 


Getting an unknown key produces undefined: 


> new Map().get('asfddfsasadf') 
undefined 


19.2.4 Iterating 


Let’s set up a Map to demonstrate how one can iterate over it. 


let map = new Map([ 
[false, 'no'], 
[true, '‘yes'], 


]); 


Maps record the order in which elements are inserted and honor that order when iterating over keys, 
values or entries. 


19.2.4.1 Iterables for keys and values 


keys () returns an iterable over the keys in the Map: 


for (let key of map.keys()) { 
console.log(key) ; 

} 

// Output: 

// false 

// true 


values() returns an iterable over the values in the Map: 


Maps and Sets 292 


for (let value of map.values()) ( 
console. log(value) ; 


} 
// Output: 


// no 
// yes 


19.2.4.2 Iterables for entries 


entries() returns the entries of the Map as an iterable over [key,value] pairs (Arrays). 


for (let entry of map.entries()) { 
console. log(entry[0], entry[1]); 


} 

// Output: 
// false no 
// true yes 


Destructuring enables you to access the keys and values directly: 


for (let [key, value] of map.entries()) { 
console.log(key, value); 


The default way of iterating over a Map is entries (): 


> map[Symbol.iterator] === map.entries 
true 


Thus, you can make the previous code snippet even shorter: 


for (let [key, value] of map) { 
console.log(key, value); 


19.2.4.3 Turning iterables into Arrays 


The spread operator (. ..) can turn an iterable into the elements of an Array. That lets us convert 
the result of Map.prototype.keys() (an iterable) into an Array: 
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> let map = new Map().set(false, 'no').set(true, 'yes'); 
> [...map.keys() ] 
[ false, true ] 


Maps are also iterable, which means that the spread operator can turn Maps into Arrays: 


> let map = new Map().set(false, 'no').set(true, 'yes'); 
> [...map] 
[ [ false, 'no' ], 

[ true, 'yes' ] ] 


19.2.5 Looping over entries 


The Map method forEach has the following signature: 
Map.prototype.forEach((value, key, map) => void, thisArg?) : void 


The signature of the first parameter mirrors the signature of the callback of Array. prototype. forEach, 
which is why the value comes first. 


let map = new Map([ 
[false, 'no'], 
[true, '‘yes'], 
1); 
map.forEach((value, key) => { 
console. log(key, value); 
}); 
// Output: 
// false no 
// true yes 


19.2.6 Mapping and filtering Maps 
You can map() and filter () Arrays, but there are no such operations for Maps. The solution: 
1. Convert the Map into an Array of [key,value] pairs. 


2. Map or filter the Array. 
3. Convert the result back to a Map. 


Pll use the following Map to demonstrate how that works. 
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let originalMap = new Map() 
.set(1, 'a') 
.set(2, 'b') 
.set(3, 'c'); 


Mapping originalMap: 


let mappedMap = new Map( // step 3 
[...originalMap] // step 1 
.map(([k, v]) => [k * 2, '_' + v]) // step 2 
); 
// Resulting Map: {2 => '_a', 4 => '_b', 6 => '_c') 


Filtering originalMap: 


let filteredMap = new Map( // step 3 
[...originalMap] // step 1 
.filter(([k, v]) => k < 3) // step 2 

)5 

// Resulting Map: {1 => 'a', 2 => 'b'} 


Step 1 is performed by the spread operator (. . .) which I have explained previously. 


19.2.7 Combining Maps 


There are no methods for combining Maps, which is why the approach from the previous section 
must be used to do so. 


Let’s combine the following two Maps: 


let mapl = new Map() 
.set(1, 'al') 
.set(2, 'b1') 
.set(3, 'c1'); 


let map2 = new Map() 
.set(2, 'b2') 
.set(3, 'c2') 
.set(4, 'd2'); 


To combine map1 and map2, I turn them into Arrays via the spread operator (. . .) and concatenate 
those Arrays. Afterwards, 1 convert the result back to a Map. All of that is done in the first line. 
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> let combinedMap = new Map([...mapl, ...map2]) 
> [...combinedMap] // convert to Array to display 
[ [ 1, 'al' J, 

[ 2, 'b2' ], 

[ 3, 'c2' l], 

[ 4, 'd2' ] ] 


19.2.8 Map API 


Constructor: 


e new Map(entries? : Iterable<[any,any]>) 
If you don’t provide the parameter iterable then an empty Map is created. If you do provide 
an iterable over [key, value] pairs then those pairs are used to add entries to the Map. For 
example: 


let map = new Map([ 
[ 1, 'one' ], 
[ 2, 'two' ], 
[ 3, 'three' ], // trailing comma is ignored 


1); 
Handling single entries: 


e Map.prototype.get(key) : any 
Returns the value that key is mapped to in this Map. If there is no key key in this Map, 
undefined is returned. 

e Map.prototype.set(key, value) : this 
Maps the given key to the given value. If there is already an entry whose key is key, it is 
updated. Otherwise, a new entry is created. This method returns this, which means that you 
can chain it. 

e Map.prototype.has(key) : boolean 
Returns whether the given key exists in this Map. 

. Map.prototype.delete(key) : boolean 
If there is an entry whose key is key, it is removed and true is returned. Otherwise, nothing 
happens and false is returned. 


Handling all entries: 


e get Map.prototype.size : number 
Returns how many entries there are in this Map. 


Maps and Sets 296 


e Map.prototype.clear() : void 
Removes all entries from this Map. 


Iterating and looping: happens in the order in which entries were added to a Map. 


. Map.prototype.entries() : Iterable<[any,any]> 
Returns an iterable with one [key,value] pair for each entry in this Map. The pairs are Arrays 
of length 2. 

. Map.prototype.forEach((value, key, collection) => void, thisArg?) : void 
The first parameter is a callback that is invoked once for each entry in this Map. If thisArg 
is provided, this is set to it for each invocation. Otherwise, this is set to undefined. 


Map.prototype.keys() : Iterable<any> 

Returns an iterable over all keys in this Map. 

Map.prototype.values() : Iterable<any> 

Returns an iterable over all values in this Map. 
Map.prototype[Symbol.iterator]() : Iterable<[any,any]> 

The default way of iterating over Maps. Refers to Map .prototype.entries. 


19.3 WeakMap 


A WeakMap is a Map that doesn't prevent its keys from being garbage-collected. That means that 
you can associate data with objects without having to worry about memory leaks. 


A WeakMap is a data structure whose keys must be objects and whose values can be arbitrary values. 
It has the same API as Map, with one significant difference: you can't iterate over the contents — 
neither the keys, nor the values, nor the entries. You can't clear a WeakMap, either. 


The rationales for these restrictions are: 


e The volatility of WeakMaps makes iteration difficult. 

e Not having clear () provides a security property. Quoting Mark Miller*: “The mapping from 
weakmap/key pair value can only be observed or affected by someone who has both the 
weakmap and the key. With clear (), someone with only the WeakMap would’ve been able 
to affect the WeakMap-and-key-to-value mapping” 


19.3.1 Using WeakMaps for private data 


Until now, there were two common ways to store private data and methods for objects”: 


“https://github.com/rwaldron/tc39-notes/blob/master/es6/2014- 11/nov- 19.md#412-should-weakmapweakset-have-a-clear-method-markm 
*[Speaking JS] “Keeping Data Private” 
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1. Via a naming convention for property keys 
2. In the environment of a constructor 


There is a neat technique involving WeakMaps that combines the advantage of the first apporach 
(simpler code) with the advantage of the second apporach (complete safety). That technique is 
demonstrated in the following code: it uses the WeakMaps _counter and _action to store private 
data. 


let _counter = new WeakMap() ; 
let _action = new WeakMap() ; 
class Countdown { 
constructor (counter, action) { 
_counter.set(this, counter); 
_action.set(this, action); 


} 

dec() 1 
let counter = _counter.get(this) ; 
if (counter < 1) return; 
counter--; 
_counter.set(this, counter); 
if (counter === 0) ( 

_action.get(this)(); 

} 

} 


Each of the two WeakMaps _counter and _action maps objects to private data. Due to how 
WeakMaps work that won’t prevent objects from being garbage-collected. As long as you keep the 
WeakMaps hidden from the outside world, the private data is safe. 


Let’s use Countdown: 


> let c = new Countdown(2, () => console. log('DONE')); 
> c.dec(); 

> c.dec(); 

DONE 


Because Countdown keeps instance-specific data elsewhere, its instance c has no own property keys: 
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> Reflect.ownKeys(c) 
[] 


19.3.2 WeakMap API 

The constructor and the four methods of WeakMap work the same as their Map equivalents: 
new WeakMap(entries? : Iterable<[any,any]>) 

WeakMap.prototype.get(key) : any 

WeakMap.prototype.set(key, value) : this 


WeakMap.prototype.has(key) : boolean 
WeakMap.prototype.delete(key) : boolean 


19.4 Set 


ECMAScript 5 doesn’t have a Set data structure, either. There are two possible work-arounds: 
e Use the keys of an object to store the elements of a set of strings. 
e Store (arbitrary) set elements in an Array: Check whether it contains an element via 
index0f (), remove elements via filter (), etc. This is not a very fast solution, but it's easy 


to implement. One issue to be aware of is that index0f () can't find the value NaN. 


ECMAScript 6 has the data structure Set which works for arbitrary values, is fast and handles NaN 
correctly. 


19.4.1 Basic operations 
Managing single elements: 


> let set = new Set(); 
> set.add('red') 


> set.has('red') 


true 

> set.delete('red') 
true 

> set.has('red') 
false 


Determining the size of a Set and clearing it: 
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> let set = new Set(); 
> set.add('red') 
> set.add('green') 


set.size 


set.clear(); 
set.size 
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19.4.2 Setting up a Set 


You can set up a Set via an iterable over the elements that make up the Set. For example, via an 
Array: 


let set = new Set(['red', 'green', 'blue']); 
Alternatively, the add method is chainable: 
let set = new Set().add('red').add('green').add('blue'); 


19.4.2.1 Pitfall: new set() has at most one argument 


The Set constructor has zero or one arguments: 


e Zero arguments: an empty Set is created. 
e One argument: the argument needs to be iterable; the iterated items define the elements of 
the Set. 


Further arguments are ignored, which may lead to unexpected results: 


Array.from(new Set(['foo', 'bar'])) 
'foo', 'bar' ] 

Array.from(new Set('foo', 'bar')) 
ai rg! ] 


"i yom. y 


For the second Set, only 'foo' is used (which is iterable) to define the Set. 


19.4.3 Comparing Set elements 


As with Maps, elements are compared similarly to ===, with the exception of NaN being like any 
other value. 
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> let set = new Set([NaN]); 
> set.size 

1 

> set.has(NaN) 

true 


Adding an element a second time has no effect: 


> let set = new Set(); 


> set.add('foo'); 
> set.size 


> set.add('foo'); 
> set.size 


Similarly to ===, two different objects are never considered equal (which can't currently be 


customized, as explained later, in the FAQ, later): 


> let set = new Set(); 


> set.add({}); 
> set.size 


> set.add({}); 
set.size 


19.4.4 Iterating 


Sets are iterable and the for-of loop works as you'd expect: 
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let set = new Set(['red', 'green', 'blue']); 
for (let x of set) { 
console. log(x) ; 


} 
// Output: 


// red 


// green 
// blue 


As you can see, Sets preserve iteration order. That is, elements are always iterated over in the order 
in which they were inserted. 


The previously explained spread operator (. . .) works with iterables and thus lets you convert a Set 
to an Array: 


let set = new Set(['red', 'green', 'blue']); 
let arr = [...set]; // ['red', 'green', 'blue'] 


We now have a concise way to convert an Array to a Set and back, which has the effect of eliminating 
duplicates from the Array: 


let arr = [3, 5, 2, 2, 5, 5]; 
let unique = [...new Set(arr)]; // [3, 5, 2] 


19.4.5 Mapping and filtering 
In contrast to Arrays, Sets don't have the methods map() and filter(). A work-around is to 
convert them to Arrays and back. 


Mapping: 


let set = new Set([1, 2, 3]); 
set = new Set([...set].map(x => x * 2)); 
// Resulting Set: {2, 4, 6} 


Filtering: 


let set = new Set([1, 2, 3, 4, 5]); 
set = new Set([...set].filter(x => (x % 2) == 0)); 
// Resulting Set: {2, 4} 
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19.4.6 Union, intersection, difference 


ECMAScript 6 Sets have no methods for computing the union (e.g. addA11), intersection (e.g. 
retainALl) or difference (e.g. removeAll). This section explains how to work around that 
limitation. 


19.4.6.1 Union 


Union (a u b): create a Set that contains the elements of both Set a and Set b. 


let a = new Set([1,2,3]); 

let b = new Set([4,3,2]); 

let union = new Set([...a, ...b]); 
ff 11,2,3,4) 


The pattern is always the same: 


e Convert one or both Sets to Arrays. 
e Perform the operation. 
e Convert the result back to a Set. 


The spread operator (. . .) inserts the elements of something iterable (such as a Set) into an Array. 
Therefore, [...a, ...b] means that a and b are converted to Arrays and concatenated. It is 
equivalent to [...a].concat([...b]). 


19.4.6.2 Intersection 


Intersection (a n b): create a Set that contains those elements of Set a that are also in Set b. 


let a = new Set([1,2,3]); 

let b = new Set([4,3,2]); 

let intersection = new Set( 
[...a].filter(x => b.has(x))); 
if 42,3} 


Steps: Convert a to an Array, filter the elements, convert the result to a Set. 


19.4.6.3 Difference 


Difference (a \ b): create a Set that contains those elements of Set a that are not in Set b. This 
operation is also sometimes called minus (-). 
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let a = new Set([1,2,3]); 

let b = new Set([4,3,2]); 

let difference = new Set( 
[...a].filter(x => !b.has(x))); 
IEA 


19.4.7 Set API 


Constructor: 


e new Set(elements? : Iterable<any>) 
If you don’t provide the parameter iterable then an empty Set is created. If you do then the 
iterated values are added as elements to the Set. For example: 


let set = new Set(['red', 'green', 'blue']); 
Single Set elements: 


e Set.prototype.add(value) : this 
Adds value to this Set. This method returns this, which means that it can be chained. 


e Set.prototype.has(value) : boolean 
Checks whether value is in this Set. 


e Set.prototype.delete(value) : boolean 
Removes value from this Set. 


All Set elements: 


e get Set.prototype.size : number 
Returns how many elements there are in this Set. 


e Set.prototype.clear() : void 
Removes all elements from this Set. 


Iterating and looping: 


e Set.prototype.values() : Iterable<any> 
Returns an iterable over all elements of this Set. 
e Set.prototype[Symbol.iterator]() : Iterable<any> 
The default way of iterating over Sets. Points to Set. prototype. values. 
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e Set.prototype.forEach((value, key, collection) => void, thisArg?) 
Loops over the elements of this Set and invokes the callback (first parameter) for each 
one. value and key are both set to the element, so that this method works similarly to 
Map.prototype.forEach. If thisArg is provided, this is set to it for each call. Otherwise, 
this is set to undefined. 


Symmetry with Map: The following two methods only exist so that the interface of Sets is similar 
to the interface of Maps. Each Set element is handled as if it were a Map entry whose key and value 
are the element. 


e Set.prototype.entries() : Iterable<[any, any]> 
e Set.prototype.keys() : Iterable<any> 


19.5 WeakSet 


A WeakSet is a Set that doesn’t prevent its elements from being garbage-collected. Consult the 
section on WeakMap for an explanation of why WeakSets don't allow iteration, looping and clearing. 


Given that you can't iterate over their elements, there are not that many use cases for WeakSets. 
They do enable you to mark objects. 


For example, if you have a factory function for proxies, you can use a WeakSet to record which 
objects were created by that factory: 


let proxies = new WeakSet(); 
function createProxy(obj) { 
let proxy = **+*; 


proxies.add (proxy) ; 
return proxy; 


function isProxy(obj) { 
return proxies.has(obj) ; 


The complete example is shown in the chapter on proxies. 


19.5.1 WeakSet API 


The constructor and the three methods of WeakSet work the same as their Set equivalents: 
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new WeakSet(elements? : Iterable<any>) 


WeakSet.prototype.add(value) 
WeakSet.prototype.has(value) 
WeakSet.prototype.delete(value) 


19.6 FAQ: Maps and Sets 


19.6.1 Why do Maps and Sets have the property size and not 
length? 


Arrays have the property length to count the number of entries. Maps and Sets have a different 
property, size. 


The reason for this difference is that length is for sequences, data structures that are indexable — 
like Arrays. size is for collections that are primarily unordered — like Maps and Sets. 


19.6.2 Why can't I configure how Maps and Sets compare keys and 
values? 


It would be nice if there were a way to configure what Map keys and what Set elements are 
considered equal. But that feature has been postponed, as it is difficult to implement properly and 
efficiently. 


19.6.3 Is there a way to specify a default value when getting 
something out of a Map? 


If you use a key to get something out of a Map, you'd occasionally like to specify a default value 
that is returned if the key is not in the Map. ES6 Maps don't let you do this directly. But you can use 
the Or operator (| |), as demonstrated in the following code. countChars returns a Map that maps 
characters to numbers of occurrences. 
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function countChars(chars) ( 
let charCounts = new Map(); 
for (let ch of chars) { 
ch = ch.toLowerCase() ; 
const prevCount = charCounts.get(ch) || 0; // (A) 
charCounts.set(ch, prevCount+1) ; 


} 


return charCounts; 


In line A, the default © is used if ch is not in the charCounts and get() returns undefined. 


19.6.4 When should | use a Map, when an object? 


If you map anything other than strings to any kind of data, you have no choice: you must use a Map. 


If, however, you are mapping strings to arbitrary data, you must decide whether or not to use an 
object. A rough general guideline is: 


e Are the keys fixed? Use an object: obj . key 
e Are the keys variable (e.g. specified via variables)? Use a Map: map. get (someKey) 


20. Typed Arrays 


Typed Arrays are an ECMAScript 6 API for handling binary data. This chapter explains how they 
work. 


20.1 Overview 
Code example: 


let typedArray = new Uint8Array([0,1,2]); 
console.log(typedArray.length); // 3 
typedArray[0] = 5; 

let normalArray = [...typedArray]; // [5,1,2] 


// The elements are stored in typedArray.buffer. 
// Get a different view on the same data: 

let dataView = new DataView(typedArray.buffer); 
console.log(dataView.getUint8(0)); // 5 


Instances of ArrayBuffer store the binary data to be processed. Two kinds of views are used to 
access the data: 


e Typed Arrays (Uint8Array, Int16Array, Float32Array, etc.) interpret the ArrayBuffer as 
an indexed sequence of elements of a single type. 

e Instances of DataView let you access data as elements of several types (Uint8, Int16, 
Float32, etc.), at any byte offset inside an ArrayBuffer. 


The following browser APIs support Typed Arrays (details are mentioned later): 


e File API 

e XMLHttpRequest 
e Fetch API 

e Canvas 

e WebSockets 

+ And more 
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20.2 Introduction 


Much data one encounters on the web is text: JSON files, HTML files, CSS files, JavaScript code, 
etc. For handling such data, JavaScript's built-in string data type works well. However, until a few 
years ago, JavaScript was not well equipped to handle binary data. On 8 February 2011, the Typed 
Array Specification 1.0* standardized facilities for handling binary data. By now, Typed Arrays are 
well supported’ by various engines. With ECMAScript 6, they became part of the core language 
and gained many methods in the process that were previously only available for Arrays (map (), 
filter (), etc.). 


The main uses cases for Typed Arrays are: 


e Processing binary data: manipulating image data in HTML Canvas elements, parsing binary 
files, handling binary network protocols, etc. 

e Interacting with native APIs: Native APIs often receive and return data in a binary format, 
which you could neither store nor manipulate well in traditional JavaScript. That meant 
that whenever you were communicating with such an API, data had to be converted from 
JavaScript to binary and back, for every call. Typed Arrays eliminate this bottleneck. One 
example of communicating with native APIs is WebGL, for which Typed Arrays were initially 
created. Section “History of Typed Arrays?” of the article “Typed Arrays: Binary Data in the 
Browser*” (by Ilmari Heikkinen for HTML5 Rocks) has more information. 


Two kinds of objects work together in the Typed Array API: 


e Buffers: Instances of ArrayBuffer hold the binary data. 
e Views: provide the methods for accessing the binary data. There are two kinds of views: 

— An instance of a Typed Array constructor (Uint8Array, Float64Array, etc.) works 
much like a normal Array, but only allows a single type for its elements and doesn’t 
have holes. 

— An instance of DataView lets you access data at any byte offset in the buffer, and 
interprets that data as one of several types (Uint8, Float64, etc.). 


This is a diagram of the structure of the Typed Array API (notable: all Typed Arrays have a common 
superclass): 


*https://www.khronos.org/registry/typedarray/specs/1.0/ 
*http://caniuse.com/#feat=typedarrays 
$http://www.html5rocks.com/en/tutorials/webgl/typed_arrays/#toc-history 
“http://www.html5rocks.com/en/tutorials/webgl/typed_arrays/#toc-history 
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TypedArray<T> 


Int8Array 


Uint8ClampedArray 


Uint16Array 


Uint32Array 


Float32Array 


20.2.1 Element types 


ArrayBuffer 


buffer 


AN 


Uint8Array 


Int16Array 


Int32Array 


Float64Array 


The following element types are supported by the API: 
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buffer 


Element type Bytes Description C type 

Int8 1 8-bit signed integer signed char 
Uint8 1 8-bit unsigned integer unsigned char 
Uint8C 1 8-bit unsigned integer (clamped conversion) unsigned char 
Int16 2 16-bit signed integer short 

Uint16 2 16-bit unsigned integer unsigned short 
Int32 4 32-bit signed integer int 

Uint32 4 32-bit unsigned integer unsigned int 
Float32 4 32-bit floating point float 

Float64 8 64-bit floating point double 


The element type Uint8C is special: it is not supported by DataView and only exists to enable 
Uint8ClampedArray. This Typed Array is used by the canvas element (where it replaces Can- 
vasPixelArray). The only difference between Uint8C and Uint8 is how overflow and underflow 
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are handled (as explained in the next section). It is recommended to avoid the former — quoting 
Brendan Eich’: 


Just to be super-clear (and I was around when it was born), Uint8ClampedAr ray is 
totally a historical artifact (of the HTML5 canvas element). Avoid unless you really are 
doing canvas-y things. 


20.2.2 Handling overflow and underflow 


Normally, when a value is out of the range of the element type, modulo arithmetic is used to convert 
it to a value within range. For signed and unsigned integers that means that: 


e The highest value plus one is converted to the lowest value (0 for unsigned integers). 
e The lowest value minus one is converted to the highest value. 


Modulo conversion for unsigned 8-bit integers: 


> let uint8 = new Uint8Array(1); 

> uint8[0] = 255; uint8[0] // highest value within range 

255 
uints[0] 


256; uint8[0] // overflow 


> 
0 

> uint8[0] 0; uint8[0] // lowest value within range 
0 

> 


uint8[0o] = -1; uint8[0] // underflow 
255 


Modulo conversion for signed 8-bit integers: 


> let int8 = new Int8Array(1); 


> int8[0] = 127; int8[0] // highest value within range 
127 

> int8[0] = 128; int8[0] // overflow 

-128 

> int8[0] = -128; int8[0] // lowest value within range 
-128 

> int8[0] = -129; int8[0] // underflow 

127 


Clamped conversion is different: 


e All underflowing values are converted to the lowest value. 
e All overflowing values are converted to the highest value. 


"https://mail.mozilla.org/pipermail/es- discuss/2015- August/043902.html 
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> let uint8c = new Uint8ClampedArray (1); 

> uint8c[O] = 255; uint8c[o] // highest value within range 
255 

> uintec[o] 


256; uint8c[0] // overflow 


255 

> uint8c[0] = 0; uint8c[o] // lowest value within range 
0 

> uint8c[0] = -1; uint8c[0o] // underflow 

0 


20.2.3 Endianness 


Whenever a type (such as Uint16) is stored as multiple bytes, endianness matters: 


e Big endian: the most significant byte comes first. For example, the Uint16 value 0xABCD is 
stored as two bytes — first 0xAB, then 0xCD. 

Little endian: the least significant byte comes first. For example, the Uint16 value 0xABCD 
is stored as two bytes — first OxCD, then OxAB. 


Endianness tends to be fixed per CPU architecture and consistent across native APIs. Typed Arrays 
are used to communicate with those APIs, which is why their endianness follows the endianness of 
the platform and can’t be changed. 


On the other hand, the endianness of protocols and binary files varies and is fixed across platforms. 
Therefore, we must be able to access data with either endianness. DataViews serve this use case and 
let you specify endianness when you get or set a value. 


Quoting Wikipedia on Endianness*: 


e Big-endian representation is the most common convention in data networking; fields in the 
protocols of the Internet protocol suite, such as IPv4, IPv6, TCP, and UDP, are transmitted in 
big-endian order. For this reason, big-endian byte order is also referred to as network byte 
order. 

e Little-endian storage is popular for microprocessors in part due to significant historical 
influence on microprocessor designs by Intel Corporation. 


You can use the following function to determine the endianness of a platform. 


*https://en.wikipedia.org/wiki/Endianness 
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const BIG_ENDIAN = Symbol ('BIG_ENDIAN'); 
const LITTLE_ENDIAN = Symbol ('LITTLE_ENDIAN'); 
function getPlatformEndianness() { 
let arr32 = Uint32Array.of(0x12345678); 
let arr8 = new Uint8Array(arr32.buffer); 
switch ((arr8[0]*0x1000000) + (arr8[1]*0x10000) + (arr8[2]x0x100) + (arr8[3l1 
)) 1 
case 0x12345678: 
return BIG_ENDIAN; 
case 0x78563412: 
return LITTLE_ENDIAN; 
default: 
throw new Error('Unknown endianness'); 


} 


There are also platforms that arrange words (pairs of bytes) with a different endianness than bytes 
inside words. That is called mixed endianness. Should you want to support such a platform then it 
is easy to extend the previous code. 


20.2.4 Negative indices 


With the bracket operator [ ], you can only use non-negative indices (starting at 0). The methods 
of ArrayBuffers, Typed Arrays and DataViews work differently: every index can be negative. If it is, 
it counts backwards from the length. In other words, it is added to the length to produce a normal 
index. Therefore -1 refers to the last element, -2 to the second-last, etc. Methods of normal Arrays 
work the same way. 


> let ui8 = Uint8Array.of(0, 1, 2); 

> ui8.slice(-1) 

Uint8Array [ 2 ] 

Offsets, on the other hand, must be non-negative. If, for example, you pass -1 to: 


DataView.prototype.getInt8(byte0ffset) 


then you get a RangeError. 


20.3 ArrayBuffers 


ArrayBuffers store the data, views (Typed Arrays and DataViews) let you read and change it. In 
order to create a DataView, you need to provide its constructor with an ArrayBuffer. Typed Array 
constructors can optionally create an ArrayBuffer for you. 
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20.3.1 ArrayBuffer constructor 


The signature of the constructor is: 
ArrayBuffer(length : number) 


Invoking this constructor via new creates an instance whose capacity is length bytes. Each of those 
bytes is initially 0. 


20.3.2 Static ArrayBuf fer methods 


e ArrayBuffer.isView(arg) 
Returns true if arg is an object and a view for an ArrayBuffer. Only Typed Arrays and 
DataViews have the required internal property [[ViewedArrayBuffer]]. That means that 
this check is roughly equivalent to checking whether arg is an instance of a Typed Array or 
of DataView. 


20.3.3 ArrayBuffer .prototype properties 


e get ArrayBuffer.prototype.byteLength 
Returns the capacity of this ArrayBuffer in bytes. 

+ ArrayBuffer.prototype.slice(start, end) 
Creates a new ArrayBuffer that contains the bytes of this ArrayBuffer whose indices are 
greater than or equal to start and less than end. start and end can be negative (see Sect. 
“Negative indices”). 


20.4 Typed Arrays 
The various kinds of Typed Array are only different w.r.t. to the type of their elements: 


e Typed Arrays whose elements are integers: Int8Array, Uint8Array, Uint8ClampedArray, 
Intl6Array, Uint16Array, Int32Array, Uint32Array 
e Typed Arrays whose elements are floats: Float32Array, Float64Array 


20.4.1 Typed Arrays versus normal Arrays 


Typed Arrays are much like normal Arrays: they have a length, elements can be accessed via the 
bracket operator [ ] and they have all of the standard Array methods. They differ from Arrays in 
the following ways: 
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e All of their elements have the same type, setting elements converts values to that type. 
e They are contiguous. Normal Arrays can have holes (indices in the range [0, arr. length) 
that have no associated element), Typed Arrays can't. 
e Initialized with zeros. This is a consequence of the previous item: 
— new Array(10) creates anormal Array without any elements (it only has holes). 
— new Uint8Array(10) creates a Typed Array whose 10 elements are all 0. 
e An associated buffer. The elements of a Typed Array ta are not stored in ta, they are stored 
in an associated ArrayBuffer that can be accessed via ta. buffer. 


20.4.2 Typed Arrays are iterable 


Typed Arrays implement a method whose key is Symbol. iterator and are therefore iterable 
(consult chapter “Iterables and iterators” for more information). That means that you can use the 
for-of loop and similar mechanisms in ES6: 


let ui8 = Uint8Array.of(0,1,2); 
for (let byte of ui8) { 
console. log (byte) ; 


} 

// Output: 
// 0 
// 1 
[L 2 


ArrayBuffers and DataViews are not iterable. 


20.4.3 Converting Typed Arrays to and from normal Arrays 


To convert a normal Array to a Typed Array, you make it the parameter of a Typed Array constructor. 
For example: 


> let tarr = new Uint8Array([0,1,2]); 


The classic way to convert a Typed Array to an Array is to invoke Array .prototype.slice on it. 
This trick works for all Array-like objects (such as arguments) and Typed Arrays are Array-like. 


> Array.prototype.slice.call(tarr) 
[ 0, 1, 2 ] 


In ES6, you can use the spread operator (. . .), because Typed Arrays are iterable: 
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> [...tarr] 
[Oy Lo 2] 


Another ES6 alternative is Array. from(), which works with either iterables or Array-like objects: 


> Array.from(tarr) 
[ 0, 1, 2 ] 


20.4.4 The Species pattern for Typed Arrays 


Some methods create new instances that are similar to this. The species pattern lets you configure 
what constructor should be used to do so. For example, if you create a subclass MyArray of Array 
then the default is that map() creates instances of MyArray. If you want it to create instances of 
Array, you can use the species pattern to make that happen. Details are explained in Sect “The 
species pattern” in the chapter on classes. 


ArrayBuffers use the species pattern in the following locations: 


e ArrayBuffer.prototype.slice() 
e Whenever an ArrayBuffer is cloned inside a Typed Array or DataView. 


Typed Arrays use the species pattern in the following locations: 


e TypedArray<T>.prototype.filter() 

e TypedArray<T>.prototype.map() 

e TypedArray<T>.prototype.slice() 

e TypedArray<T>.prototype.subarray() 


DataViews don't use the species pattern. 


20.4.5 The inheritance hierarchy of Typed Arrays 


As you could see in the diagram at the beginning of this chapter, all Typed Array classes 
(Uint8Array etc.) have a common superclass. I’m calling that superclass TypedAr ray, but it is not 
directly accessible from JavaScript (the ES6 specification calls it the intrinsic object %TypedArray%). 
TypedArray.prototype houses all methods of Typed Arrays. 


20.4.6 Static TypedArray methods 
Both static TypedArray methods are inherited by its subclasses (Uint8Array etc.). 


20.4.6.1 TypedArray.of() 


This method has the signature: 
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TypedArray.of(... items) 


It creates a new Typed Array that is an instance of this (the class on which of () was invoked). 
The elements of that instance are the parameters of of (). 


You can think of of () as a custom literal for Typed Arrays: 


> Float32Array.of(0.151, -8, 3.7) 
Float32Array [ 0.151, -8, 3.7 ] 


20.4.6.2 TypedArray.from() 


This method has the signature: 
TypedArray<U>.from(source : Iterable<T>, mapfn? : T => U, thisArg?) 


It converts the iterable source into an instance of this (a Typed Array). 


For example, normal Arrays are iterable and can be converted with this method: 


> Uinti6Array.from([0, 1, 2]) 
Uintl6Array [ 0, 1, 2 ] 


Typed Arrays are iterable, too: 


> let uil6 = Uintl6Array.from(Uint8Array.of(0, 1, 2)); 
> uil6 instanceof Uintl6Array 
true 


The optional mapfn lets you transform the elements of source before they become elements of the 
result. Why perform the two steps mapping and conversion in one go? Compared to performing the 
first step separately, via source.map(), there are two advantages: 


1. No intermediate Array or Typed Array is needed. 
2. When converting a Typed Array to a Typed Array whose elements have a higher precision, 
the mapping step can make use of that higher precision. 


To illustrate the second advantage, let's use map() to double the elements of a Typed Array: 
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> Int8Array.of(127, 126, 125) .map(x => 2 x x) 
Int8Array [ -2, -4, -6 ] 


As you can see, the values overflow and are coerced into the Int8 range of values. If map via from(), 
you can choose the type of the result so that values don't overflow: 


> Intl6Array.from(Int8Array.of(127, 126, 125), x => 2 x x) 
Intl6Array [ 254, 252, 250 ] 


According to Allen Wirfs-Brock”, mapping between Typed Arrays was what motivated the mapfn 
parameter of from(). 


20.4.7 TypedArray.prototype properties 


Indices accepted by Typed Array methods can be negative (they work like traditional Array methods 
that way). Offsets must be non-negative. For details, see Sect. “Negative indices”. 


20.4.7.1 Methods specific to Typed Arrays 


The following properties are specific to Typed Arrays, normal Arrays don't have them: 


e get TypedArray<T>.prototype.buffer : ArrayBuffer 
Returns the buffer backing this Typed Array. 
e get TypedArray<T>.prototype.byteLength : number 
Returns the size in bytes of this Typed Array’s buffer. 
e get TypedArray<T>.prototype.byteOffset : number 
Returns the offset where this Typed Array “starts” inside its ArrayBuffer. 
e TypedArray<T>.prototype.set(arrayOrTypedArray, offset=0) : void 
Copies all elements of arrayOrTypedArray to this Typed Array. The element at index 0 of 
arrayOrTypedArray is written to index offset of this Typed Array (etc.). 

- If arrayOrTypedArray is a normal Array, its elements are converted to numbers who 
are then converted to the element type T of this Typed Array. 

- If arrayOrTypedArray is a Typed Array then each of its elements is converted directly 
to the appropriate type for this Typed Array. If both Typed Arrays have the same element 
type then faster, byte-wise copying is used. 

TypedArray<T>.prototype.subarray(begin=0, end=this.length) : TypedAr- 
ray<T> 

Returns a new Typed Array that has the same buffer as this Typed Array, but a (generally) 
smaller range. If begin is non-negative then the first element of the resulting Typed Array 
is this[begin], the second this[begin+1] (etc.). If begin in negative, it is converted 
appropriately. 


"https://twitter.com/awbjs/status/585199958661472257 
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20.4.7.2 Array methods 


The following methods are basically the same as the methods of normal Arrays: 


e TypedArray<T>.prototype.copyWithin(target : number, start : number, end 
= this.length) : This 
Copies the elements whose indices are between start (including) and end (excluding) to 
indices starting at target. If the ranges overlap and the former range comes first then 
elements are copied in reverse order to avoid overwriting source elements before they are 
copied. 

e TypedArray<T>.prototype.entries() : Iterable<[number,T]> 
Returns an iterable over [index,element] pairs for this Typed Array. 

e TypedArray<T>.prototype.every(callbackfn, thisArg?) 

Returns true if callbackfn returns true for every element of this Typed Array. Otherwise, 
it returns false. every () stops processing the first time cal lbackfn returns false. 

e TypedArray<T>.prototype.fill(value, start=0, end=this.length) : void 
Set the elements whose indices range from start to end to value. 

e TypedArray<T>.prototype.filter(callbackfn, thisArg?) : TypedArray<T> 
Returns a Typed Array that contains every element of this Typed Array for which call- 
backfn returns true. In general, the result is shorter than this Typed Array. 

e TypedArray<T>.prototype.find(predicate : T => boolean, thisArg?) : T 
Returns the first element for which the function predicate returns true. 

e TypedArray<T>.prototype.findIndex(predicate : T => boolean, thisArg?) 
number 
Returns the index of the first element for which predicate returns true. 

e TypedArray<T>.prototype.forEach(callbackfn, thisArg?) : void 
Iterates over this Typed Array and invokes callbackfn for each element. 

e TypedArray<T>.prototype.index0f(searchElement, fromIndex=0) : number 
Returns the index of the first element that strictly equals searchElement. The search starts 
at fromIndex. 

e TypedArray<T>.prototype.join(separator : string = ',') : string 
Converts all elements to strings and concatenates them, separated by separator. 

e TypedArray<T>.prototype.keys() : Iterable<number> 
Returns an iterable over the indices of this Typed Array. 

e TypedArray<T>.prototype.lastIndex0f (searchElement, fromIndex?) : number 
Returns the index of the last element that strictly equals searchElement. The search starts 
at fromIndex, backwards. 

e get TypedArray<T>.prototype.length : number 
Returns the length of this Typed Array. 

e TypedArray<T>.prototype.map(callbackfn, thisArg?) : TypedArray<T> 
Returns a new Typed Array in which every element is the result of applying callbackfn to 
the corresponding element of this Typed Array. 
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e TypedArray<T>.prototype.reduce(callbackfn : (previousValue : any, cur- 
rentElement : T, currentIndex : number, array : TypedArray<T>) => any, 
initialValue?) : any 
callbackfn is fed one element at a time, together with the result that was computed so far 
and computes a new result. Elements are visited from left to right. 

e TypedArray<T>.prototype.reduceRight(callbackfn : (previousValue : any, 
currentElement : T, currentIndex : number, array : TypedArray<T>) => any, 
initialValue?) : any 
callbackfn is fed one element at a time, together with the result that was computed so far 
and computes a new result. Elements are visited from right to left. 

e TypedArray<T>.prototype.reverse() : This 
Reverses the order of the elements of this Typed Array and returns this. 

e TypedArray<T>.prototype.slice(start=0, end=this.length) : TypedArray<T> 
Create a new Typed Array that only has the elements of this Typed Array whose indices are 
between start (including) and end (excluding). 

e TypedArray<T>.prototype.some(callbackfn, thisArg?) 

Returns true if callbackfn returns true for at least one element of this Typed Array. 
Otherwise, it returns false. some () stops processing the first time cal Lbackfn returns true. 

e TypedArray<T>.prototype.sort(comparefn? : (number, number) => number) 
Sorts this Typed Array, as specified via comparefn. If comparefn is missing, sorting is done 
ascendingly, by comparing via the less-than operator (<). 

e TypedArray<T>.prototype.toLocaleString(reserved1?, reserved2?) 

e TypedArray<T>.prototype.toString() 

e TypedArray<T>.prototype.values() : Iterable<T> 
Returns an iterable over the values of this Typed Array. 


Due to all of these methods being available for Arrays, you can consult the following two sources 
to find out more about how they work: 


e The following methods are new in ES6 and explained in chapter “New Array features”: 
copyWithin, entries, fill, find, findIndex, keys, values. 
e All other methods are explained in chapter “Arrays?” of “Speaking JavaScript”. 


Note that while normal Array methods are generic (any Array-like this is OK), the methods listed 
in this section are not (this must be a Typed Array). 


Shttp://speakingjs.com/es5/ch18.html 
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20.4.8 «ElementType»Array constructor 


Each Typed Array constructor has a name that follows the pattern «ElementType»Array, where 
«ElementType» is one of the element types in the table at the beginning. That means that 
there are 9 constructors for Typed Arrays: Int8Array, Uint8Array, Uint8ClampedArray (el- 
ement type Uintsc), Int16Array, Uintl16Array, Int32Array, Uint32Array, Float32Array, 
Float64Array. 


Each constructor has five overloaded versions — it behaves differently depending on how many 
arguments it receives and what their types are: 


e «ElementType»Array(buffer, byteOffset=0, length?) 
Creates a new Typed Array whose buffer is buf fer. It starts accessing the buffer at the given 
byteOffset and will have the given length. Note that length counts elements of the Typed 
Array (with 1-4 bytes each), not bytes. 

e «ElementType»Array (length) 
Creates a Typed Array with the given length and the appropriate buffer (whose size in bytes 
is length * «ElementType»Array.BYTES_PER_ELEMENT). 

e «ElementType»Array() 
Creates a Typed Array whose length is 0. It also creates an associated empty ArrayBuffer. 

e «ElementType»Array (typedArray) 
Creates a new Typed Array that has the same length and elements as typedArray. Values 
that are too large or small are converted appropriately. 

e «ELementType»Array (arrayLikeObject) 
Treats arrayLikeObject like an Array and creates a new TypedArray that has the same 
length and elements. Values that are too large or small are converted appropriately. 


The following code shows three different ways of creating the same Typed Array: 


let tarr = new Uint8Array([1,2,3]); 
let tarr = Uint8Array.of(1,2,3); 


let tarr = new Uint8Array(3) ; 
tarr[0] = 0; 

tarr[1] 
tarr[2] 


ot ot 
N FR 


20.4.9 Static «ElementType»Array properties 


e «ElementType»Array.BYTES_PER_ELEMENT 
Counts how many bytes are needed to store a single element: 
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> Uint8Array.BYTES_PER_ELEMENT 
1 

> Intl6Array.BYTES_PER_ELEMENT 
2 

> Float64Array.BYTES_PER_ELEMENT 
8 


20.4.10 «ElementType»Array.prototype properties 


e «ElementType»Array.prototype.BYTES_PER_ELEMENT 
The same as «ElementType»Array.BYTES_PER_ELEMENT. 


20.4.11 Concatenating Typed Arrays 


Typed Arrays don't have a method concat(), like normal Arrays do. The work-around is to use 
the method 


typedArray.set(arrayOrTypedArray, offset=0) 


That method copies an existing Typed Array (or normal Array) into typedArray at index offset. 
Then you only have to make sure that typedArray is big enough to hold all (Typed) Arrays you 
want to concatenate: 


function concatenate(resultConstructor, ...arrays) { 
let totalLength = 0; 
for (let arr of arrays) { 
totalLength += arr.length; 


let result = new resultConstructor (totalLength) ; 
let offset = 0; 
for (let arr of arrays) { 

result.set(arr, offset); 

offset += arr.length; 


return result; 
} 
console. log(concatenate(Uint8Array, 
Uint8Array.of(1, 2), Uint8Array.of(3, 4))); 
// Uint8Array [1, 2, 3, 4] 
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20.5 DataViews 


20.5.1 DataV1ew constructor 


e DataView(buffer, byteOffset=0, byteLength=buffer.byteLength-byteOffset) 
Creates a new DataView whose data is stored in the ArrayBuffer buffer. By default, the new 
DataView can access all of buffer, the last two parameters allow you to change that. 


20.5.2 DataView. prototype properties 


e get DataView. prototype. buffer 
Returns the ArrayBuffer of this DataView. 
e get DataView. prototype.byteLength 
Returns how many bytes can be accessed by this DataView. 
e get DataView. prototype. byteOffset 
Returns at which offset this DataView starts accessing the bytes in its buffer. 
e DataView. prototype. get«ElementType» (byteOffset, littleEndian=false) 
Reads a value from the buffer of this DataView. 
— «ElementType» can be: Float32, Float64, Int8, Int16, Int32, Uint8, Uint16, 
Uint32 
e DataView.prototype.set«ElementType» (byteOffset, value, littleEndian=false) 
Writes value to the buffer of this DataView. 
— «ElementType» can be: Float32, Float64, Int8, Int16, Int32, Uint8, Uint16, 
Uint32 


20.6 Browser APIs that support Typed Arrays 


Typed Arrays have been around for a while, so there are quite a few browser APIs that support 
them. 


20.6.1 File API 


The file API’ lets you access local files. The following code demonstrates how to get the bytes of a 
submitted local file in an ArrayBuffer. 


*http://www.w3.org/TR/FileAPI/ 
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let fileInput = document.getElementBylId('filelnput'); 
let file = filelnput.files[0]; 
let reader = new FileReader(); 
reader.readAsArrayBuffer(file); 
reader.onload = function () { 

let arrayBuffer = reader.result; 


}; 


20.6.2 XMLHttpRequest 


In newer versions of the XMLHttpRequest API”, you can have the results delivered in an 
ArrayBuffer: 


let xhr = new XMLHttpRequest(); 
xhr.open('GET', someUrl); 
xhr.responseType = 'arraybuffer'; 


xhr.onload = function () ( 
let arrayBuffer = xhr.response; 


}; 


xhr.send(); 


20.6.3 Fetch API 


Similarly to XMLHttpRequest, the Fetch APT lets you request resources. But it is based on Promises, 
which makes it more convenient to use. The following code demonstrates how to download the 
content pointed to by url as an ArrayBuffer: 


fetch(url) 

.then (request => request.arrayBuffer()) 
.then(arrayBuffer => ++»); 

20.6.4 Canvas 


Quoting the HTMLS5 specification”: 


“http://www.w3.org/TR/XMLHttpRequest/ 
“https://fetch.spec.whatwg.org/ 
“http://www.w3.org/TR/html5/scripting- 1.html#the-canvas-element 
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The canvas element provides scripts with a resolution-dependent bitmap canvas, which 
can be used for rendering graphs, game graphics, art, or other visual images on the fly. 


The 2D Context of canvas”? lets you retrieve the bitmap data as an instance of Uint8ClampedArray: 


let canvas = document.getElementBylId('my_canvas'); 

let context = canvas.getContext('2d'); 

let imageData = context.getImageData(0, 0, canvas.width, canvas.height) ; 
let uint8ClampedArray = imageData.data; 


20.6.5 WebSockets 


WebSockets'* let you send and receive binary data via ArrayBuffers: 


let socket = new WebSocket('ws://127.0.0.1:8081'); 
socket.binaryType = 'arraybuffer''; 


// Wait until socket is open 

socket.addEventListener('open', function (event) { 
// Send binary data 
let typedArray = new Uint8Array (4); 
socket.send(typedArray.buffer) ; 

}); 


// Receive binary data 
socket.addEventListener('message', function (event) { 
let arrayBuffer = event.data; 


H); 
20.6.6 Other APIs 


e WebGL“ uses the Typed Array API for: accessing buffer data, specifying pixels for texture 
mapping, reading pixel data, and more. 
e The Web Audio APT‘ lets you decode audio data” submitted via an ArrayBuffer. 


*http://www.w3.org/TR/2dcontext/ 
*http://www.w3.org/TR/websockets/ 
https://www.khronos.org/registry/webgl/specs/latest/2.0/ 
*Shttp://www.w3.org/TR/webaudio/ 
“http://www.w3.org/TR/webaudio/#dfn-decodeAudioData 
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e Media Source Extensions’*: The HTML media elements are currently <audio> and <video>. 
The Media Source Extensions API enables you to create streams to be played via those 
elements. You can add binary data to such streams via ArrayBuffers, Typed Arrays or 
DataViews. 

e Communication with Web Workers”: If you send data to a Worker via postMessage()”, 
either the message (which will be cloned) or the transferable objects can contain ArrayBuffers. 

e Cross-document communication”: works similarly to communication with Web Workers and 
also uses the method postMessage(). 


20.7 Extended example: JPEG SOFO decoder 


lap) The code of the following example is on GitHub”. And you can run it online”. 


The example is a web pages that lets you upload a JPEG file and parses its structure to determine 
the height and the width of the image and more. 


20.7.1 The JPEG file format 


A JPEG file is a sequence of segments (typed data). Each segment starts with the following four 
bytes: 


e Marker (two bytes): declares what kind of data is stored in the segment. The first of the two 
bytes is always OxFF. Each of the standard markers has a human readable name. For example, 
the marker OxFFCO has the name “Start Of Frame (Baseline DCT)”, short: “SOFO0”. 


e Length of segment (two bytes): how long is this segment (in bytes, including the length itself)? 


JPEG files are big-endian on all platforms. Therefore, this example demonstrates how important it 
is that we can specify endianness when using DataViews. 


20.7.2 The JavaScript code 


The following function processArrayBuffer () is an abridged version of the actual code; I’ve 
removed a few error checks to reduce clutter. processArrayBuffer () receives an ArrayBuffer 
with the contents of the submitted JPEG file and iterates over its segments. 


*Shttp://www.w3.org/TR/media-source/ 

http://www.w3.org/TR/workers/ 

20h ttp://www.w3.org/TR/workers/+dom-worker-postmessage 
**https://html.spec.whatwg.org/multipage/comms.html#crossDocumentMessages 
2https://github.com/rauschma/typed-array-demos 
“http://rauschma.github.io/typed-array-demos/ 
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// JPEG is big endian 
var IS_LITTLE_ENDIAN = false; 


function processArrayBuffer(arrayBuffer) { 
try { 
var dv = new DataView(arrayBuffer) ; 


var ptr = 2; 
while (true) { 


var lastPtr = ptr; 
enforceValue(OxFF, dv.getUint8(ptr), 
"Not a marker'); 


ptr++; 

var marker = dv.getUint8(ptr); 

ptr++; 

var len = dv.getUint16(ptr, IS_LITTLE_ENDIAN) ; 
ptr += len; 


logInfo('Marker: '+hex(marker)+' ('+len+' byte(s))'); 


// Did we find what we were looking for? 


if (marker === 0xC0) { // SOFO 
logInfo(decodeSOFO(dv, lastPtr)); 
break; 

} 


} 
} catch (e) { 
logError(e.message); 


This code uses the following helper functions (that are not shown here): 


e enforceValue() throws an error if the expected value (first parameter) doesn’t match the 
actual value (second parameter). 


e logInfo() and logError () display messages on the page. 
e hex() turns a number into a string with two hexadecimal digits. 


decodeSOF0() parses the segment SOFO: 
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function decodeSOFO(dv, start) { 

// Example (16x16): 

// FF CO 00 11 08 00 10 00 10 03 01 22 OO 02 11 01 03 11 01 

var data = {}; 

start += 4; // skip marker OxFFCO and segment length 0x0011 

var data = { 
bitsPerColorComponent: dv.getUint8(start), // usually 0x08 
imageHeight: dv.getUint16(start+1, IS_LITTLE_ENDIAN) , 
imagewidth: dv.getUint16(start+3, IS_LITTLE_ENDIAN) , 
numberOfColorComponents: dv.getUint8(start+5), 

$5 

return JSON.stringify(data, null, 4); 


More information on the structure of JPEG files: 


e “JPEG: Syntax and structure?” (on Wikipedia) 
e “JPEG File Interchange Format: File format structure?” (on Wikipedia) 


20.8 Availability 


Much of the Typed Array API is implemented by all modern JavaScript engines, but several features 
are new to ECMAScript 6: 


e Static methods borrowed from Arrays: TypedArray<T>.from(), TypedArray<T>.of () 

e Prototype methods borrowed from Arrays: TypedArray<T>.prototype.map() etc. 

e Typed Arrays are iterable 

e Support for the species pattern 

e An inheritance hierarchy where TypedArray<T> is the superclass of all Typed Array classes 


» cc 


It may take a while until these are available everywhere. As usual, kangax 
table?” describes the status quo. 


ES6 compatibility 


*4https://en.wikipedia.org/wiki/JPEG#Syntax_and_structure 
$ "https: //en.wikipedia.org/wiki/JPEG_File Interchange Format+File format structure 
?Shttps://kangax.github.io/compat-table/es6/*typed_arrays 


21. Iterables and iterators 


ECMAScript 6 introduces a new interface for iteration, Iterable. This chapter explains how it 
works, which language constructs consume data via it (e.g., the new for-of loop) and which sources 
provide data via it (e.g., Arrays). 


21.1 Overview 
The following two entities play important roles in iteration: 


e Iterable: An iterable is a data structure that wants to make its elements accessible to the 
public. It does so by implementing a method whose key is Symbol. iterator. That method 
is a factory for iterators. 

e Iterator: a pointer for traversing the elements of a data structure (think cursors in databases). 


The following values are iterable: 


e Arrays 

e Strings 

e Maps 

e Sets 

e DOM data structures (work in progress) 

Not iterable: plain objects (which are not a data structure, strictly speaking; a more in-depth 
explanation is given later) 


Language constructs that access data via the iteration protocol: 


e Destructuring via an Array pattern: 
let [a,b] = new Set(['a', 'b', 'c']); 


e for-of loop: 


328 
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for (let x of ['a', 'b', 'c']) 4 
console. log(x) ; 


} 


e Array.from(): 

let arr = Array.from(new Set(['a', 'b', 'c'])); 
e Spread operator (...): 

let arr = [...new Set(['a', 'b', 'c'])]; 


e Constructors of Maps and Sets: 


let map = new Map([[false, 'no'], [true, 'yes']]); 
let set = new Set(['a', 'b', 'c']); 


e Promise.all(), Promise.race(): 


Promise.all(iterableOverPromises).then(:--); 
Promise.race(iterableOverPromises).then(:-:); 


e yields: 


yield* anIterable; 


21.2 Iterability 
The idea of iterability is as follows. 


e Data consumers: JavaScript has language constructs that consume data. For example, for-of 
loops over values and the spread operator (. . .) inserts values into Arrays or function calls. 

e Data sources: The data consumers could get their values from a variety of sources. For 
example, you may want to iterate over the elements of an Array, the key-value entries in 
a Map or the characters of a string. 


It’s not practical for every consumer to support all sources, especially because it should be possible 
to create new sources (e.g. via libraries). Therefore, ES6 introduces the interface Iterable. Data 
consumers use it, data sources implement it: 
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Data consumers Interface Data sources 

for-of loop Arrays 
Iterable aps 

spread operator Strings 


Given that JavaScript does not have interfaces, Iterable is more of a convention: 


e Source: A value is considered iterable if it has a method whose key is the symbol Sym- 
bol.iterator that returns a so-called iterator. The iterator is an object that returns values 
via its method next(). We say: it enumerates items, one per method call. 

e Consumption: Data consumers use the iterator to retrieve the values they are consuming. 


Let’s see what consumption looks like for an Array arr. First, you create an iterator via the method 
whose key is Symbol. iterator: 


> let arr = Ear "De. ter]; 
> let iter = arr[Symbol.iterator](); 


Then you call the iterator’s method next () repeatedly to retrieve the items “inside” the Array: 


> iter.next() 

value: 'a', done: false } 
iter.next() 

value: 'b', done: false } 
iter.next() 

value: 'c', done: false } 
iter.next() 

value: undefined, done: true } 


AV AV AV AS 


As you can see, next () returns each item wrapped in an object, as the value of the property value. 
The boolean property done indicates when the end of the sequence of items has been reached. 


Iterable and iterators are part of a so-called protocol (methods plus rules for using them) for 
iteration. A key characteristic of this protocol is that it is sequential: the iterator returns values one 
at a time. That means that if an iterable data structure is non-linear (such as a tree), iteration will 
linearize it. 
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21.3 Iterable data sources 


Pll use the for-of loop (which is explained in more detail later) to iterate over various kinds of 
iterable data. 


21.3.1 Arrays 


Arrays (and Typed Arrays) are iterables over their elements: 


for (let x of ['a', 'b']) { 
console. log(x) ; 


} 
// Output: 


// ta! 
// 'bh! 


21.3.2 Strings 


Strings are iterable, but they enumerate Unicode code points, each of which may comprise one or 
two JavaScript characters: 


for (let x of 'a\uD83D\uDCOA') { 
console. log(x) ; 


} 
// Output: 
fd. ta! 


// '\uD83D\uDCOA' (crocodile emoji) 


You have just seen that primitive values can be iterable, too. A value doesn’t have to be an 
object in order to be iterable. 


21.3.3 Maps 


Maps are iterables over their entries. Each entry is encoded as a [key, value] pair, an Array with 
two elements. The entries are always enumerated deterministically, in the same order in which they 
were added to the map. 
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let map = new Map().set('a', 1).set('b', 2); 
for (let pair of map) { 
console. log(pair) ; 
} 
// Output: 
ff Va", 1] 
ff TB"; 2] 


Note that WeakMaps are not iterable. 


21.3.4 Sets 


Sets are iterables over their elements (which are enumerated in the same order in which they were 
added to the Set). 


let set = new Set().add('a').add('b'); 
for (let x of set) ( 
console. log(x) ; 


} 

// Output: 
// ra! 

// "bit 


Note that WeakSets are not iterable. 


21.3.5 arguments 


Even though the special variable arguments is more or less obsolete in ECMAScript 6 (due to rest 
parameters), it is iterable: 


function printArgs() { 
for (let x of arguments) { 
console. log(x); 
} 


} 
printArgs('a', 'b'); 


// Output: 

// ! a L] 

// tp! 

21.3.6 DOM data structures 


Most DOM data structures will eventually be iterable: 
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for (let node of document.querySelectorAll('div')) { 
} 


Note that implementing this functionality is work in progress. But it is relatively easy to do so, 
because the symbol Symbol. iterator can't clash with existing property keys. 


21.3.7 Iterable computed data 


Not all iterable content does have to come from data structures, it could also be computed on the fly. 
For example, all major ES6 data structures (Arrays, Typed Arrays, Maps, Sets) have three methods 
that return iterable objects: 


e entries() returns an iterable over entries encoded as [key, value] Arrays. For Arrays, the 
values are the Array elements and the keys are their indices. For Sets, each key and value are 
the same — the Set element. 

e keys() returns an iterable over the keys of the entries. 

e values() returns an iterable over the values of the entries. 


Let's see what that looks like. entries () gives you a nice way to get both Array elements and their 
indices: 


let arr = ['a', 'b', 'c']; 
for (let pair of arr.entries()) { 
console. log(pair) ; 


} 

// Output: 
// EO, 'a'] 
fi ig *b"] 
ff C2; "e"] 


21.3.8 Plain objects are not iterable 


Plain objects (as created by object literals) are not iterable: 


for (let x of {}) { // TypeError 
console. log(x) ; 


t 


Why aren’t objects iterable over properties, by default? The reasoning is as follows. There are two 
levels at which you can iterate in JavaScript: 
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1. The program level: iterating over properties means examining the structure of the program. 
2. The data level: iterating over a data structure means examining the data managed by the 
program. 


Making iteration over properties the default would mean mixing those levels, which would have 
two disadvantages: 


e You can’t iterate over the properties of data structures. 
e Once you iterate over the properties of an object, turning that object into a data structure 
would break your code. 


Therefore, the safest way to iterate over properties is via a tool function. For example, via 
objectEntries(), whose implementation is shown later (future ECMAScript versions may have 
something similar built in): 


let obj = { first: 'Jane', last: 'Doe' }; 


for (let [key,value] of objectEntries(obj)) { 
console. log(’${key}: S{value}°); 


// Output: 
// first: Jane 
// last: Doe 


It is also important to remember that iterating over the properties of an object is mainly interesting 
if you use objects as Maps’. But we only do that in ES5 because we have no better alternative. In 
ECMAScript 6, we have the built-in data structure Map. 


21.4 Iterating language constructs 


The following ES6 language constructs make use of the iteration protocol: 


Destructuring via an Array pattern 
e for-of loop 

«e Array. from() 

Spread operator (.. .) 
Constructors of Maps and Sets 


e Promise.all(), Promise.race() 
e yieldx 


The next sections describe each one of them in detail. 


*[Speaking JS] “Pitfalls: Using an Object as a Map” 
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21.4.1 Destructuring via an Array pattern 
Destructuring via Array patterns works for any iterable: 


let set = new Set().add('a').add('b').add('c'); 


let [x,y] = set; 
// x='a's y='b! 


let [first, ...rest] = set; 
// first='a'; rest=['b','c']; 


21.4.2 The for-of loop 


for-of is a new loop in ECMAScript 6. One form of it looks like this: 


for (let x of iterable) { 


} 


This loop iterates over iterable, assigns each of the enumerated items to the iteration variable x 
and lets you process it in the body. The scope of x is the loop, it doesn’t exist outside it. 


Note that the iterability of iterable is required, otherwise for-of can’t loop over a value. 
That means that non-iterable values must be converted to something iterable. For example, via 
Array .from(), which turns Array-like values and iterables into Arrays: 


let arrayLike = { length: 2, 0: 'a', 1: 'b' }; 


for (let x of arrayLike) { // TypeError 
console. log(x) ; 


for (let x of Array.from(arrayLike)) { // OK 
console. log(x) ; 


t 


I expect for-of to mostly replace Array.prototype.forEach(), because it is more versatile 
(forEach() only works for Array-like values) and will be faster long term (see FAQ at the end). 


21.4.2.1 Iteration variables: tet declarations vs. var declarations 


If you Let-declare the iteration variable, a fresh binding (slot) will be created for each iteration. That 
can be seen in the following code snippet where we save the current binding of elem for later, via 
an arrow function. Afterwards, you can see that the arrow functions don’t share the same binding 
for elem, they each have a different one. 
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let arr = []; 
for (let elem of [0, 1, 2]) { 
arr.push(() => elem); // save ‘elem for later 


} 
console.log(arr.map(f => f())); // [0, 1, 2] 


// `elem` only exists inside the loop: 
console.log(elem); // ReferenceError: elem is not defined 


A const declaration works the same way as a let declaration (but the bindings are immutable). 


It is instructive to see how things are different if you var-declare the iteration variable. Now all 
arrow functions refer to the same binding of elem. 


let arr = []; 
for (var elem of [0, 1, 2]) € 
arr.push(() => elem); 
} 
console.log(arr.map(f => f())); // [2, 2, 2] 


// “elem' exists in the surrounding function: 
console.log(elem); // 2 


Having one binding per iteration is very helpful whenever you create functions via a loop (e.g. to 
add event listeners). 


You also get per-iteration bindings in for loops and for-in loops if you use let. Details are 
explained in the chapter on variables. 


21.4.2.2 Iterating with existing variables, object properties and Array elements 


So far, we have only seen for-of with a declared iteration variable. But there are several other 
forms. 


You can iterate with an existing variable: 


let x; 
for (x of ['a', 'b']) { 
console. log(x) ; 


You can also iterate with an object property: 
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let obj = {}; 
for (obj.prop of ['a', 'b']) { 
console. log(obj.prop) ; 


And you can iterate with an Array element: 


let arr = []; 
for (arr[0] of ['a', 'b']) { 
console.log(arr[0]); 


21.4.2.3 Iterating with a destructuring pattern 


Combining for-of with destructuring is especially useful for iterables over [key, value] pairs 
(encoded as Arrays). That's what Maps are: 


let map = new Map().set(false, 'no').set(true, 'yes'); 
for (let [k,v] of map) { 
console. log(*key = ${k}, value = ${v} ); 
} 
// Output: 
// key = false, value = no 
// key = true, value = yes 


Array .prototype.entries() also returns an iterable over [key, value] pairs: 
let arr = ['a', 'b', 'c']; 


for (let [k,v] of arr.entries()) { 
console.log('key = ${k}, value = ${v} ); 


t 

// Output: 

// key = 0, value =a 
// key = 1, value = b 
// key = 2, value = c 


Therefore, entries() gives you a way to treat enumerated items differently, depending on their 
position: 
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/** Same as arr.join(', ') x/ 
function toString(arr) { 
let result = ''; 
for (let [i,elem] of arr.entries()) { 
if (i > 0) 4 
result += ', '; 
} 
result += String(elem); 


} 


return result; 


This function is used as follows: 


> toString(['eeny', 'meeny', 'miny', 'moe']) 
'eeny, meeny, miny, moe' 


21.4.3 Array.from() 


Array.from() converts iterable and Array-like values to Arrays. It is also available for typed 
Arrays. 


> Array.from(new Map().set(false, 'no').set(true, 'yes')) 
[[false,'no'], [true,'yes']] 

> Array.from({ length: 2, 0: 'hello', 1: 'world' }) 
['hello', 'world'] 


Array.from() works as expected for a subclass of Array (which inherits this class method) - it 
converts iterables to instances of the subclass. 


21.4.4 The spread operator (...) 


The spread operator inserts the values of an iterable into an Array: 
> let arr = ['b', 'c']; 
> ["a"; asar a” 


[Bets o", MEN "d'] 


That means that it provides you with a compact way to convert any iterable to an Array: 
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let arr = [...iterable]; 


The spread operator also turns an iterable into the arguments of a function, method or constructor 
call: 


> Math.max(...[-1, 8, 3]) 
8 


21.4.5 Maps and Sets 


The constructor of a Map turns an iterable over [key, value] pairs into a Map: 


> let map = new Map([['uno', 'one'], ['dos', 'two']]); 
> map.get('uno') 

‘one! 

> map.get('dos') 

"two! 


The constructor of a Set turns an iterable over elements into a Set: 


> let set = new Set(['red', 'green', 'blue']); 
> set.has('red') 

true 

> set.has('yellow' ) 

false 


The constructors of WeakMap and WeakSet work similarly. Furthermore, Maps and Sets are iterable 
themselves (WeakMaps and WeakSets aren’t), which means that you can use their constructors to 
clone them. 


21.4.6 Promises 
Promise.all() and Promise.race() accept iterables over Promises: 


Promise.all(iterableOverPromises) .then(::-); 
Promise.race(iterableOverPromises).then(--:); 


21.4.7 yieldx 


yields yields all items enumerated by an iterable. 
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function» yieldALlValuesOf(iterable) { 
yield* iterable; 


The most important use case for yieldx is to recursively call a generator (which produces something 
iterable). 


21.5 Implementing iterables 


The iteration protocol looks as follows. 


Iterable: Iterator: 
traversable data structure pointer for traversing iterable 


ET En 


[Symbol.iterator]() 


An object becomes iterable (“implements” the interface Iterable) if it has a method (own or 
inherited) whose key is Symbol .iterator. That method must return an iterator, an object that 
enumerates the items “inside” the iterable via its method next (). 


In TypeScript notation, the interfaces for iterables and iterators look as follows’. 


interface Iterable ( 
[System.iterator]() : Iterator; 
} 
interface IteratorResult { 
value: any; 
done: boolean; 
} 
interface Iterator { 
next() : IteratorResult; 
return? (value? : any) : IteratorResult; 


return is an optional method that we’ll get to later (so is throw(), but it is practically never used 
for iterators and therefore explained in the chapter on generators). Let's first implement a dummy 
iterable to get a feeling for how iteration works. 


“Based on “Closing iterators”, slides by David Herman. 


Iterables and iterators 


let iterable = { 
[Symbol.iterator]() { 
let step = 0; 
let iterator = { 


next() Y 
if (step <= 2) ( 
step++; 
} 
switch (step) { 
case 1: 
return { value: 
case 2: 
return { value: 
default: 
return { value: 
} 
} 


}; 


return iterator; 


}; 


Let's check that iterable is, in fact, iterable: 


for (let x of iterable) { 
console. log(x) ; 

} 

// Output: 

// hello 

// world 


"hello', done: false }; 
'world', done: false }; 


undefined, done: true }; 
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The code executes three steps, with the counter step ensuring that everything happens in the right 
order. First we, return the value 'hello', then the value 'world' and then we indicate that the end 
of the enumerated items has been reached. Each item is wrapped in an object with the properties: 


e value which holds the actual item and 


e done which is a boolean flag that indicates whether the end has been reached, yet. 


You can omit done if it is false and value if it is undefined. That is, the switch statement could 


be written as follows. 
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switch (step) { 
case 1: 
return { value: 
case 2: 
return { value: 
default: 


"hello' }; 


"world! $; 


return { done: true }; 
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As is explained in the the chapter on generators, there are cases where you want even the last item 
with done: true to have a value. Otherwise, next () could be simpler and return items directly 
(without wrapping them in objects). The end of iteration would then be indicated via a special value 


(e.g., a symbol). 


Let’s look at one more implementation of an iterable. The function iterateOver() returns an 
iterable over the arguments that are passed to it: 


function iterateOver(... 
let index = 0; 
let iterable = { 


args) { 


[Symbol.iterator]() { 
let iterator = { 


next() { 
if ( 


index < args.length) { 
return { value: args[index++] }; 


} else { 


$5 


return { done: true }; 


return iterator; 


} 


return iterable; 


// Using `iterateOver()` 
for (let x of iterateOve 
console. log(x) ; 


// Output: 
// fee 


r('fee', MPa "to; 'fum')) { 
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// $1 
// fo 
// fum 


21.5.1 Iterators that are iterable 


The previous function can be simplified if the iterable and the iterator are the same object: 


function iterateOver(...args) { 
let index = 0; 
let iterable = { 
[Symbol.iterator]() { 
return this; 


}o 
next() { 
if (index < args.length) { 
return { value: args[index++] }; 
} else { 
return { done: true }; 
} 
}, 


}; 


return iterable; 


Even if the original iterable and the iterator are not the same object, it is still occasionally useful if 
an iterator has the following method (which also makes it an iterable): 


[Symbol.iterator]() { 
return this; 


All built-in ES6 iterators follow this pattern (via a common prototype, see the chapter on generators). 
For example, the default iterator for Arrays: 


> let arr = []; 

> let iterator = arr[Symbol.iterator](); 

> iterator[Symbol.iterator]() === iterator 
true 


Why is it useful if an iterator is also an iterable? for-of only works for iterables, not for iterators. 
Because Array iterators are iterable, you can continue an iteration in another loop: 
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let arr = ['a', 'b']; 
let iterator = arr[Symbol.iterator] (); 


for (let x of iterator) ( 
console.log(x); // a 
break; 


// Continue with same iterator: 
for (let x of iterator) { 
console. log(x); // b 


One use case for continuing an iteration is that you can remove initial items (e.g. a header) before 
processing the actual content via for-of. 


21.5.2 Optional iterator methods: return() and throw( ) 


Two iterator methods are optional: 


e return() gives an iterator the opportunity to clean up if an iteration ends prematurely. 
e throw() is about forwarding a method call to a generator that is iterated over via yield. It 
is explained in the chapter on generators. 


21.5.2.1 Closing iterators via return() 


As mentioned before, the optional iterator method return() is about letting an iterator clean up if 
it wasn’t iterated over until the end. It closes an iterator. In for—-of loops, premature (or abrupt, in 
spec language) termination can be caused by: 


e break 
e continue (if you continue an outer loop, continue acts like a break) 
e throw 


e return 


In each of these cases, for-of lets the iterator know that the loop won't finish. Let's look at an 
example, a function readLinesSync that returns an iterable of text lines in a file and would like to 
close that file no matter what happens: 


Iterables and iterators 345 


function readLinesSync(fileName) ( 
let file = -::; 
return { 


next() { 
if (file.isAtEndOfFile()) { 
file.close() ; 
return { done: true }; 


a 
return() ( 
file.close(); 
return { done: true }; 


}, 
}; 


Due to return(), the file will be properly closed in the following loop: 


// Only print first line 

for (let line of readLinesSync(fileName)) 4 
console.log(x); 
break; 


The return() method must return an object. That is due to how generators handle the return 
statement and will be explained in the chapter on generators. 


The following constructs close iterators that aren't completely “drained”: 


e for-of 

e yieldx 

e Destructuring 

e Array.from() 

. Map(), Set(), WeakMap(), WeakSet () 
e Promise.all(),Promise.race() 


A later section has more information on closing iterators. 
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21.6 More examples of iterables 


In this section, we look at a few more examples of iterables. Most of these iterables are easier to 
implement via generators. The chapter on generators shows how. 


21.6.1 Tool functions that return iterables 


Tool functions and methods that return iterables are just as important as iterable data structures. 
The following is a tool function for iterating over the own properties of an object. 


function objectEntries(obj) { 


let index = 0; 


// In ES6, you can use strings or symbols as property keys, 
// Reflect.ownKeys() retrieves both 
let propKeys = Reflect.ownKeys (obj) ; 


return { 
[Symbol.iterator]() { 
return this; 


}o 
next() { 
if (index < propKeys.length) { 
let key = propKeys[index]; 
index++; 
return { value: [key, obj[key]] 7; 
j else { 
return { done: true }; 
} 
} 
ES 
} 
let obj = { first: 'Jane', last: 'Doe' }; 
for (let [key,value] of objectEntries(obj)) { 
console.log(`${key}: ${value}`); 
} 
// Output: 


// first: Jane 
// Tast: Doe 
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21.6.2 Combinators for iterables 


Combinators’ are functions that combine existing iterables to create new ones. 


21.6.2.1 take(n, iterable) 


Let’s start with the combinator function take(n, iterable), which returns an iterable over the 
first n items of iterable. 


function take(n, iterable) { 
let iter = iterable[Symbol.iterator] (); 
return { 
[Symbol.iterator]() { 
return this; 


ee 
next() { 
if (n> 0) { 
n-~3 
return iter.next(); 
} else { 
return { done: true }; 
} 
} 


}; 

} 

let arr = ['a', 'b', 'c', 'd']; 

for (let x of take(2, arr)) { 
console. log(x) ; 

} 

// Output: 

// a 

// b 


A This version of take () doesn’t close the iterator iter. How to do that is shown later, after 
I explain what closing an iterator actually means. 


21.6.2.2 zip(...iterables) 


zip turns n iterables into an iterable of n-tuples (encoded as Arrays of length n). 


3“Combinator” (in HaskellWiki) describes what combinators are. 
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function zip(...iterables) { 
let iterators = iterables.map(i => i[Symbol.iterator] ()); 
let done = false; 
return { 
[Symbol.iterator]() { 
return this; 


$y 
next() { 
if (!done) { 
let items = iterators.map(i => i.next()); 
done = items.some(item => item.done) ; 
if (!done) { 
return { value: items.map(i => i.value) }; 
} 
// Done for the first time: close all iterators 
for (let iterator of iterators) { 
iterator.return(); 
} 
} 
// We are done 
return { done: true }; 
} 


As you can see, the shortest iterable determines the length of the result: 


let zipped = zip(['a', 'b', tet], ['d', te", 'f', 'g']); 
for (let x of zipped) { 
console. log(x) ; 


} 
// Output: 


JJ Mat, ! 


21.6.3 Infinite iterables 


Some iterable may never be done. 
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function naturalNumbers() { 
let n = 0; 
return { 
[Symbol.iterator]() { 
return this; 


}, 
next() { 

return { value: n++ }; 
} 


With an infinite iterable, you must not iterate over “all” of it. For example, by breaking from a 
for-of loop: 


for (let x of naturalNumbers()) { 
if (x > 2) break; 
console. log(x) ; 


Or by only accessing the beginning of an infinite iterable: 


let [a, b, c] = naturalNumbers(); 
// a=0; b=1; c=2; 


Or by using a combinator. take () is one possibility: 


for (let x of take(3, naturalNumbers())) { 
console. log(x) ; 

} 

// Output: 

// 9 

ff A 

ie: 


The “length” of the iterable returned by zip() is determined by its shortest input iterable. That 
means that zip() and naturalNumbers() provide you with the means to number iterables of 
arbitrary (finite) length: 
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let zipped = zip(['a', 'b', 'c'], naturalNumbers()); 
for (let x of zipped) { 
console. log(x) ; 
} 
// Output: 
pt Pas 0] 
dd Dors A] 
e LE 24 


21.7 FAQ: iterables and iterators 


21.7.1 Isn't the iteration protocol slow? 


You may be worried about the iteration protocol being slow, because a new object is created for 
each invocation of next (). However, memory management for small objects is fast in modern 
engines and in the long run, engines can optimize iteration so that no intermediate objects need to 
be allocated. A thread on es-discuss* has more information. 


21.7.2 Can | reuse the same object several times? 


In principle, nothing prevents an iterator from reusing the same iteration result object several times 
- Pd expect most things to work well. However, there will be problems if a client caches iteration 
results: 


let iterationResults = []; 

let iterator = iterable[Symbol.iterator] (); 

let iterationResult; 

while (!(iterationResult = iterator.next()).done) ( 
iterationResults.push(iterationResult); 


If an iterator reuses its iteration result object, iterationResults will, in general, contain the same 
object multiple times. 


21.7.3 Why doesn't ECMAScript 6 have iterable combinators? 


You may be wondering why ECMAScript 6 does not have iterable combinators, tools for working 
with iterables or for creating iterables. That is because the plans are to proceed in two steps: 


“https://esdiscuss.org/topic/performance- of-iterator-next-as-specified 
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e Step 1: standardize an iteration protocol. 
e Step 2: wait for libraries based on that protocol. 


Eventually, one such library or pieces from several libraries will be added to the JavaScript standard 
library. 


If you want to get an impression of what such a library could look like, take a look at the standard 
Python module itertools’. 


21.7.4 Aren't iterables difficult to implement? 


Yes, iterables are difficult to implement — if you implement them manually. The next chapter will 
introduce generators that help with this task (among other things). 


21.8 The ECMAScript 6 iteration protocol in depth 


The iteration protocol comprises the following iterfaces (I have omitted throw() from Iterator, 
which is only supported by yield» and optional there): 


interface Iterable { 
[System.iterator]() : Iterator; 
} 
interface Iterator { 
next() : IteratorResult; 
return? (value? : any) : IteratorResult; 
} 
interface IteratorResult { 
value : any; 
done : boolean; 


re ted The spec has a section on the iteration protocol’. 
+ 


*https://docs.python.org/3/library/itertools.html 
*http://www.ecma-international.org/ecma-262/6.0/#sec-iteration 
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21.8.1 Iteration 


Rules for next(): 


e As long as the iterator still has values x to produce, next() returns objects { value: x, 
done: false }. 

e After the last value was iterated over, next () should always return an object whose property 
done is true. 


21.8.1.1 The IteratorResult 


The property done of an iterator result doesn’t have to be true or false, truthy or falsy is enough. 
All built-in language mechanisms let you omit done: false. 


21.8.1.2 Iterables that return fresh iterators vs. those that always return the 
same iterator 


Some iterables produce a new iterator each time they are asked for one. For example, Arrays: 


function getIterator(iterable) { 
return iterable[Symbol.iterator] (); 


let iterable = ['a', 'b']; 
console. lLog(getIterator(iterable) === getIterator(iterable)); // false 


Other iterables return the same iterator each time. For example, generator objects: 


function» elements() ( 
yield 'a'; 
yield 'b'; 
} 
let iterable = elements(); 
console. log(getIterator(iterable) === getIterator(iterable)); // true 


Whether an iterable produces a fresh iterators or not matter when you iterate over the same iterable 
multiple times. For example, via the following function: 
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function iterateTwice(iterable) { 
for (let x of iterable) { 
console. log(x); 


} 
for (let x of iterable) { 


console. log(x); 


With fresh iterators, you can iterate over the same iterable multiple times: 


iterateTwice(['a', 'b']); 
// Output: 

// a 

// b 
// a 
// b 


If the same iterator is returned each time, you can't: 


iterateTwice(elements()); 
// Output: 

// a 

// b 


Note that each iterator in the standard library is also an iterable. Its method [Symbol. iterator] () 
return this, meaning that it always returns the same iterator (itself). 


21.8.2 Closing iterators 
The iteration protocol distinguishes two ways of finishing an iterator: 
e Exhaustion: the regular way of finishing an iterator is by retrieving all of its values. That is, 
one calls next () until it returns an object whose property done is true. 
e Closing: by calling return(), you tell the iterator that you don’t intend to call next(), 
anymore. 


Rules for calling return(): 


e return() is an optional method, not all iterators have it. Iterators that do have it are called 
closable. 
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e return() should only be called if an iterator hasn't be exhausted. For example, for-of calls 
return() whenever it is left “abruptly” (before it is finished). The following operations cause 
abrupt exits: break, continue (with a label of an outer block), return, throw. 


Rules for implementing return(): 


e The method call return(x) should normally produce the object { done: true, value: x 
}, but language mechanisms only throw an error (source in spec’) if the result isn’t an object. 
e After return() was called, the objects returned by next () should be done, too. 


The following code illustrates that the for-of loop calls return () if it is aborted before it receives 
a done iterator result. That is, return() is even called if you abort after receiving the last value. 
This is subtle and you have to be careful to get it right when you iterate manually or implement 
iterators. 


function createlterable() { 
let done = false; 
let iterable = { 
[Symbol.iterator]() { 
return this; 


in 
next() { 
if (!done) { 
done = true; 
return { done: false, value: 'a' }; 
} else { 
return { done: true, value: undefined }; 
} 
}o 


return() { 
console.log('return() was called!'); 
le 
}; 


return iterable; 


for (let x of createIterable()) { 
console. log(x) ; 
// There is only one value in the iterable and 
// we abort the loop after receiving it 
break; 


"http://www.ecma-international.org/ecma-262/6.0/#sec-iteratorclose 


Iterables and iterators 355 


} 
// Output: 


// a 


// return() was called! 


21.8.2.1 Closable iterators 


An iterator is closable if it has a method return(). Not all iterators are closable. For example, Array 
iterators are not: 


> let iterable = ['a', 'b', 'c']; 

> let iterator = iterable[Symbol.iterator](); 
> 'return' in iterator 

false 


Generator objects are closable by default. For example, the ones returned by the following generator 
function: 


function» elements() ( 


yield 'a'; 
yield 'b'; 
yield 'c'; 


If you invoke return() on the result of elements (), iteration is finished: 


let iterator = elements(); 
iterator.next() 

value: 'a', done: false } 
iterator.return() 

value: undefined, done: true } 
iterator.next() 

value: undefined, done: true } 


mm NV ra Vo V WY 


If an iterator is not closable, you can continue iterating over it after an abrupt exit (such as the one 
in line A) from a for-of loop: 
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function twoLoops(iterator) { 
for (let x of iterator) { 
console. log(x); 
break; // (A) 
} 
for (let x of iterator) { 
console. log(x); 


} 
function getIterator(iterable) { 


return iterable[Symbol.iterator] (); 


twoLoops(getIterator(['a', 'b', 'c'])); 
// Output: 

// a 

// b 

fi € 


Conversely, elements () returns a closable iterator and the second loop inside twoLoops () doesn't 
have anything to iterate over: 


twoLoops (elements()); 
// Output: 


// a 


21.8.2.2 Preventing iterators from being closed 


The following class is a generic solution for preventing iterators from being closed. It does so by 
wrapping the iterator and forwarding all method calls except return(). 


class PreventReturn { 
constructor (iterator) { 
this.iterator = iterator; 
} 
/*xx Must also be iterable, so that for-of works */ 
[Symbol.iterator]() 4 
return this; 
} 
next() { 
return this.iterator.next(); 
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return(value = undefined) { 
return { done: false, value }; 


} 


// Not relevant for iterators: `throw()` 


If we use PreventReturn, the result of the generator elements () won't be closed after the abrupt 
exit in the first loop of twoLoops(). 


function» elements() ( 


yield 'a'; 
yield 'b'; 
yield 'c'; 


J 
function twoLoops(iterator) { 
for (let x of iterator) { 
console.log(x); 
break; // abrupt exit 
} 
for (let x of iterator) { 
console. log(x); 


} 
twoLoops (elements()); 
// Output: 


// a 


twoLoops (new PreventReturn(elements())); 
// Output: 

// a 

// b 

if € 


There is an another way of making generators unclosable: All generator objects produced by 
the generator function elements () have the prototype object elements .prototype. Via ele- 
ments.prototype, you can hide the default implementation of return() (which resides in a 
prototype of elements . prototype) as follows: 
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// Make generator object unclosable 
// Warning: may not work in transpilers 
elements.prototype.return = undefined; 


twoLoops(elements()) 5 
// Output: 

// a 

// b 

Hp € 


21.8.2.3 Handling clean-up in generators via try-finally 


Some generators need to clean up (release allocated resources, close open files, etc.) after iteration 
over them is finished. Naively, this is how we’d implement it: 


functionx genFunc() { 
yield 'a'; 
yield 'b'; 


console.log('Performing cleanup'); 


In a normal for-of loop, everything is fine: 


for (let x of genFunc()) 4 
console.log(x); 

} 

// Output: 

fia 

// b 


// Performing cleanup 


However, if you exit the loop after the first yield, execution seemingly pauses there forever and 
never reaches the cleanup step: 
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for (let x of genFunc()) { 
console. log(x) ; 
break; 


} 
// Output: 


// a 


What actually happens is that, whenever one leaves a for-of loop early, for-of sends a return() 
to the current iterator. That means that the cleanup step isn't reached because the generator function 
returns beforehand. 


Thankfully, this is easily fixed, by performing the cleanup in a finally clause: 


functionx genFunc() { 


try ( 
yield 'a'; 
yield 'b'; 


} finally { 
console.log('Performing cleanup'); 


Now everything works as desired: 


for (let x of genFunc()) 4 
console. log(x) ; 
break; 

} 

// Output: 

// a 


// Performing cleanup 


The general pattern for using resources that need to be closed or cleaned up in some manner is 
therefore: 
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function» funcThatUsesResource() { 
let resource = allocateResource(); 
try { 


} finally { 
resource.deallocate() ; 


21.8.2.4 Handling clean-up in manually implemented iterators 


let iterable = { 
[Symbol.iterator]() { 


function hasNextValue() { °°: } 
function getNextValue() { =: } 
function cleanUp() { +- } 
let returnedDoneResult = false; 
return { 

next() { 


if (hasNextValue()) ( 
let value = getNextValue(); 
return { done: false, value: value }; 
} else { 
if (!returnedDoneResult) { 
// Client receives first ‘done’ iterator result 
// => won’t call 'return()” 
cleanUp() ; 
returnedDoneResult = true; 


} 


return { done: true, value: undefined }; 


}, 
return() { 
cleanup () ; 


}; 


Note that you must call cleanUp() when you are going to return a done iterator result for the first 
time. You must not do it earlier, because then return() may still be called. This can be tricky to get 
right. 
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21.8.2.5 Closing iterators you use 
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If you use iterators, you should close them properly. In generators, you can let for-of do all the 


work for you: 


px 
x Converts a (potentially infinite) sequence of 
x iterated values into a sequence of length ‘n° 
*/ 
functionx take(n, iterable) { 
for (let x of iterable) { 
if (n <= 0) { 
break; // closes iterable 


} 
n-=; 
yield x; 


If you manage things manually, more work is required: 


function» take(n, iterable) { 
let iterator = iterable[Symbol.iterator](); 
while (true) { 
let (value, done} = iterator.next(); 
if (done) break; // exhausted 
if (n <= 0) { 
// Abrupt exit 
maybeCloselterator (iterator); 


break; 
} 
yield value; 
n=>5 
} 
} 
function maybeCloseIterator(iterator) { 
if (typeof iterator.return === 'function') { 
iterator.return(); 
} 
} 


Even more work is necessary if you don’t use generators: 
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function take(n, iterable) { 
let iter = iterable[Symbol.iterator] (); 
return { 
[Symbol.iterator]() { 
return this; 


a 
next() { 

if (n> 0) { 
n-~3 
return iter.next(); 

} else { 
maybeCLloselIterator (iter); 
return { done: true }; 

} 

he 
return() { 
n = 0; 
maybeCloseIterator (iter); 
} 
}5 
} 
21.8.3 Checklist 


e Documenting an iterable: provide the following information. 
— Does it return fresh iterators or the same iterator each time? 
— Are its iterators closable? 
e Implementing an iterator: 
— Clean-up activity must happen if either an iterator is exhausted or if return() is called. 
* In generators, try-finally lets you handle both in a single location. 
— After an iterator was closed via return(), it should not produce any more iterator 
results via next(). 
e Using an iterator manually (vs. via for-of etc.): 
- Don't forget to close the iterator via return, if — and only if — you don’t exhaust it. 
Getting this right can be tricky. 
e Continuing to iterate over an iterator after an abrupt exit: The iterator must either be 
unclosable or made unclosable (e.g. via a tool class). 


22. Generators 


Generators, a new feature of ECMAScript 6, are functions that can be paused and resumed (think 
cooperative multitasking or coroutines). This helps with many applications: iterators, asynchronous 
programming, etc. This chapter explains how generators work and gives an overview of their 
applications. 


lap) The following GitHub repository contains the example code: generator-examples’ 


22.1 Overview 


Two important applications of generators are: 


1. Implementing iterables 
2. Blocking on asynchronous function calls 


The following subsections give brief overviews of these applications, more thorough explanations 
are provided later (plus discussions of other applications). 


22.1.1 Implementing iterables via generators 


The following function returns an iterable over the properties of an object, one [key, value] pair per 
property: 


// The asterisk after 'function' means that 
// “objectEntries' is a generator 
function» objectEntries(obj) ( 

let propKeys = Reflect.ownKeys(obj) ; 


for (let propKey of propKeys) { 
// “yield” returns a value and then pauses 
// the generator. Later, execution continues 
// where it was previously paused. 
yield [propKey, obj[propKey]]; 


*https://github.com/rauschma/generator-examples 
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How exactly objectEntries() works is explained later. It is used like this: 


let jane = { first: 'Jane', last: 'Doe' }; 

for (let [key,value] of objectEntries(jane)) { 
console. log(’${key}: S{value}°); 

} 

// Output: 

// first: Jane 

// last: Doe 


22.1.2 Blocking on asynchronous function calls 


In the following code, I use the control flow library co? to asynchronously retrieve two JSON files. 
Note how, in line A, execution blocks (waits) until the result of Promise. all() is ready. That means 
that the code looks synchronous while performing asynchronous operations. 


co(functionx () { 
try { 

let [croftStr, bondStr] = yield Promise.all([ // (A) 
getFile('http://localhost: 8000/croft.json'), 
getFile('http://localhost:8000/bond.json'), 

D; 

let croftJson = JSON.parse(croftStr) ; 

let bondJson = JSON.parse(bondStr) ; 


console. log(croftJson) ; 
console. log(bondJson) ; 
} catch (e) { 
console.log('Failure to read: ' + e); 


13 


getFile(url) retrieves the file pointed to by ur l. Its implementation is shown later. I’ll also explain 
how co works. 


22.2 What are generators? 


Generators are functions that can be paused and resumed (think cooperative multitasking or 
coroutines), which enables a variety of applications. 


As a first example, consider the following generator function whose name is genFunc: 


?https://github.com/tj/co 
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functionx genFunc() { 
console. log('First'); 
yield; // (A) 
console. log('Second'); // (B) 


Two things distinguish genFunc from a normal function declaration: 


e It starts with the “keyword” functionx. 
e It is paused in the middle via yield. 


Calling genFunc does not execute it. Instead, it returns a so-called generator object that lets us 
control genFunc’s execution: 


> let genObj = genFunc(); 


genFunc() is initially suspended at the beginning of its body. The method genObj.next() 
continues the execution of genFunc, until the next yield: 


> gen0bj.next() 
First 
{ value: undefined, done: false } 


As you can see in the last line, genObj .next() also returns an object. Let’s ignore that for now. It 
will matter once we look at generators as iterators. 


genFunc is now paused in line A. If we call next () again, execution resumes and line B is executed: 


> gen0bj.next() 
Second 
{ value: undefined, done: true } 


Afterwards, the function is finished, execution has left the body and further calls of genObj .next () 
have no effect. 


22.2.1 Ways of creating generators 


There are four ways in which you can create generators: 


1. Via a generator function declaration: 
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functionx genFunc() { +++ } 
let gen0bj = genFunc(); 


2. Via a generator function expression: 


const genFunc = function» () { +++ }; 
let gen0bj = genFunc(); 


3. Via a generator method definition in an object literal: 


let obj = { 
* generatorMethod() { 


} 
35 
let gen0bj = obj.generatorMethod () ; 


4. Via a generator method definition in a class definition (which can be a class declaration or a 
class expression): 


class MyClass { 
x generatorMethod() { 


} 


} 
let myInst = new MyClass(); 
let gen0bj = myInst.generatorMethod(); 


22.2.2 Roles played by generators 


Generators can play three roles: 


1. Iterators (data producers): Each yield can return a value via next(), which means that 
generators can produce sequences of values via loops and recursion. Due to generator objects 
implementing the interface Iterable (which is explained in the chapter on iteration), these 
sequences can be processed by any ECMAScript 6 construct that supports iterables. Two 
examples are: for-of loops and the spread operator (.. .). 

2. Observers (data consumers): yield can also receive a value from next() (via a parameter). 
That means that generators become data consumers that pause until a new value is pushed 
into them via next(). 

3. Coroutines (data producers and consumers): Given that generators are pausable and can 
be both data producers and data consumers, not much work is needed to turn them into 
coroutines (cooperatively multitasked tasks). 


The next sections provide deeper explanations of these roles. 
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22.3 Generators as iterators (data production) 


O For this section, you should be familiar with ES6 iteration. The previous chapter has more 
information. 


As explained before, generator objects can be data producers, data consumers or both. This section 
looks at them as data producers, where they implement both the interfaces Iterable and Iterator 
(shown below). That means that the result of a generator function is both an iterable and an iterator. 
The full interface of generator objects will be shown later. 


interface Iterable { 
[Symbol.iterator]() : Iterator; 
} 
interface Iterator { 
next() : IteratorResult; 
return? (value? : any) : IteratorResult; 
} 
interface IteratorResult { 
value : any; 
done : boolean; 


A generator function produces a sequence of values via yield, a data consumer consumes thoses 
values via the iterator method next (). For example, the following generator function produces the 
values 'a' and 'b!: 


functionx genFunc() { 


yield 'a'; 
yield 'b'; 


This interaction shows how to retrieve the yielded values via the generator object genObj: 


Generators 368 


let gen0bj = genFunc(); 

gen0bj.next () 

value: 'a', done: false } 

gen0bj.next() 

value: 'b', done: false } 

gen0bj.next() // done: true => end of sequence 
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value: undefined, done: true } 


22.3.1 Ways of iterating over a generator 


As generator objects are iterable, ES6 language constructs that support iterables can be applied to 
them. The following three ones are especially important. 


First, the for-of loop: 


for (let x of genFunc()) 4 
console.log(x); 

} 

// Output: 

// a 

// b 


Second, the spread operator (. . .), which turns iterated sequences into elements of an array (consult 
the chapter on parameter handling for more information on this operator): 


let arr = [...genFunc()]; // ['a', 'b'] 
Third, destructuring: 


> let [x, y] = genFunc(); 
> x 
Vat 
> y 
bp! 


22.3.2 Returning from a generator 


The previous generator function did not contain an explicit return. An implicit return is 
equivalent to returning undefined. Let's examine a generator with an explicit return: 
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functionx genFuncWithReturn() { 
yield 'a'; 
yield 'b'; 
return 'result'; 


The returned value shows up in the last object returned by next (), whose property done is true: 


let genObjWithReturn = genFuncWithReturn() ; 
genObjWithReturn.next() 

value: 'a', done: false } 
genObjWithReturn.next() 

value: 'b', done: false } 
genObjWithReturn.next() 

value: 'result', done: true } 
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However, most constructs that work with iterables ignore the value inside the done object: 


for (let x of genFuncWithReturn()) { 
console. log(x) ; 


} 
// Output: 


// a 
// b 


let arr = [...genFuncWithReturn()]; // ['a', 'b'] 


yield, an operator for making recursive generator calls, does consider values inside done objects. 
It is explained later. 


22.3.3 Example: iterating over properties 


Let’s look at an example that demonstrates how convenient generators are for implementing 
iterables. The following function, objectEntries(), returns an iterable over the properties of an 
object: 
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function» objectEntries(obj) ( 
// In ES6, you can use strings or symbols as property keys, 
// Reflect.ownKeys() retrieves both 
let propKeys = Reflect.ownKeys (obj) ; 


for (let propKey of propKeys) { 
yield [propKey, obj[propKey]]; 


This function enables you to iterate over the properties of an object jane via the for-of loop: 


let jane = { first: 'Jane', last: 'Doe' }; 

for (let [key,value] of objectEntries(jane)) { 
console. log(’${key}: S{value}°); 

} 

// Output: 

// first: Jane 

// last: Doe 


For comparison — an implementation of objectEntries() that doesn’t use generators is much 
more complicated: 


function objectEntries(obj) { 
let index = 0; 
let propKeys = Reflect.ownKeys (obj) ; 


return { 
[Symbol.iterator]() { 
return this; 


ty 
next() { 
if (index < propKeys.length) { 
let key = propKeys[index]; 
index++; 
return { value: [key, obj[key]] 7; 
j else { 
return { done: true }; 
} 
} 


}; 
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22.3.4 You can only yield in generators 


A significant limitation of generators is that you can only yield while you are (statically) inside a 
generator function. That is, yielding in callbacks doesn’t work: 


function* genFunc() { 
['a', 'b'].forEach(x => yield x); // SyntaxError 


yield is not allowed inside non-generator functions, which is why the previous code causes a syntax 
error. In this case, it is easy to rewrite the code so that it doesn't use callbacks (as shown below). But 
unfortunately that isn't always possibe. 


functionx genFunc() { 
for (let x of ['a', 'b']) 4 
yield x; // OK 


The upsides of this limitation are explained later: they make generators easier to implement and 
compatible with event loops. 


22.3.5 Recursion via yield (for output) 


You can only use yield within a generator function. Therefore, if you want to implement a recursive 
algorithm with generator, you need a way to call one generator from another one. This section shows 
that that is more complicated than it sounds, which is why ES6 has a special operator, yield*, for 
this. For now, I only explain how yield* works if both generators produce output, Pll later explain 
how things work if input is involved. 


How can one generator recursively call another generator? Let’s assume you have written a 
generator function foo: 


functionx foo() { 
yield 'a'; 
yield 'b'; 


How would you call foo from another generator function bar? The following approach does not 
work! 
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functionx bar() { 


yield 'x'; 
foo(); // does nothing! 
yield 'y'; 


} 


Calling foo() returns an object, but does not actually execute foo(). That's why ECMAScript 6 
has the operator yield» for making recursive generator calls: 


functionx bar() { 


yield 'x'; 
yieldx foo(); 
yield 'y'; 


// Collect all values yielded by bar() in an array 
let arr = [...bar()]; 
// pes Nae MD by] 


Internally, yield* works roughly as follows: 


function bar() { 
yield 'x'; 
for (let value of foo()) { 
yield value; 


} 
yield 'y'; 
} 


The operand of yield» does not have to be a generator object, it can be any iterable: 


function bla() ( 
yield 'sequence'; 
yieldx ['of', 'yielded']; 
yield 'values'; 


let arr = [...bla()]; 
// ['sequence', 'of', 'yielded', 'values'] 


22.3.5.1 yield» considers end-of-iteration values 


Most constructs that support iterables ignore the value included in the end-of-iteration object (whose 
property done is true). Generators provide that value via return. The result of yieldx is the end- 
of-iteration value: 
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functionx genFuncWithReturn() { 
yield 'a'; 
yield 'b'; 
return 'The result'; 

} 

function» logReturned(gen0bj) { 
let result = yieldx gen0bj; 
console.log(result); // (A) 

} 


If we want to get to line A, we first must iterate over all values yielded by logReturned (): 


> [...logReturned(genFuncWithReturn())] 
The result 
[ Mer: ger py ] 


22.3.5.2 Iterating over trees 


Iterating over a tree with recursion is simple, writing an iterator for a tree with traditional means 
is complicated. That’s why generators shine here: they let you implement an iterator via recursion. 
As an example, consider the following data structure for binary trees. It is iterable, because it has a 
method whose key is Symbol. iterator. That method is a generator method and returns an iterator 
when called. 


class BinaryTree { 
constructor(value, left=null, right=null) { 
this.value = value; 
this. left = left; 
this.right = right; 


/x*x Prefix iteration */ 
x [Symbol.iterator]() { 
yield this.value; 
if (this.left) ( 
yield* this.left; 
} 
if (this.right) { 
yield» this.right; 


} 


The following code creates a binary tree and iterates over it via for-of: 
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let tree = new BinaryTree('a', 
new BinaryTree('b', 
new BinaryTree('c'), 
new BinaryTree('d')), 
new BinaryTree('e')); 


for (let x of tree) { 
console.log(x); 


} 

// Output: 
// a 
// b 
HF 
// d 
He 


22.4 Generators as observers (data consumption) 


As consumers of data, generator objects conform to the second half of the generator interface, 
Observer: 


interface Observer { 
next(value? : any) : void; 
return(value? : any) : void; 
throw(error) : void; 


As an observer, a generator pauses until it receives input. There are three kinds of input, transmitted 
via the methods specified by the interface: 


e next () sends normal input. 
e return() terminates the generator. 
e throw() signals an error. 


22.4.1 Sending values via next () 


If you use a generator as an observer, you send values to it via next () and it receives those values 
via yield: 
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function» dataConsumer() ( 
console. log('Started'); 
console. log('1. ${yield}*); // (A) 
console. log(`2. ${yield}°); 
return 'result'; 


Let’s use this generator interactively. First, we create a generator object: 
> let genObj = dataConsumer(); 


We now call gen0bj .next (), which starts the generator. Execution continues until the first yield, 
which is where the generator pauses. The result of next () is the value yielded in line A (undefined, 
because yield doesn't have an operand). In this section, we are not interested in what next () 
returns, because we only use it to send values, not to retrieve values. 


> gen0bj.next() 
Started 
{ value: undefined, done: false } 


We call next () two more times, in order to send the value 'a' to the first yield and the value 'b' 
to the second yield: 


> gen0bj.next('a') 
l. a 
{ value: undefined, done: false } 


> genObj.next('b') 
24.6 
{ value: 'result', done: true } 


The result of the last next() is the value returned from dataConsumer(). done being true 
indicates that the generator is finished. 


Unfortunately, next() is asymmetric, but that can’t be helped: It always sends a value to the 
currently suspended yield, but returns the operand of the following yield. 


22.4.1.1 The first next() 


When using a generator as an observer, it is important to note that the only purpose of the first 
invocation of next () is to start the observer. It is only ready for input afterwards, because this first 
invocation has advanced execution to the first yield. Therefore, you can’t send input via the first 
next() — you even get an error if you do: 
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> functionx g() { yield } 
> g().next('hello') 
TypeError: attempt to send 'hello' to newborn generator 


The following utility function fixes this issue: 


px 
x Returns a function that, when called, 
* returns a generator object that is immediately 
x ready for input via 'next()” 
x / 
function coroutine(generatorFunction) { 
return function (...args) { 
let generatorObject = generatorFunction(...args); 
generatorObject.next() ; 
return generatorObject; 


$5 


To see how coroutine() works, let's compare a wrapped generator with a normal one: 


const wrapped = coroutine(functionx () ( 
console.log( "First input: ${yield}°); 
return 'DONE'; 

$»; 

const normal = functionx () { 
console.log(' First input: ${yield} ); 
return 'DONE'; 

$; 


The wrapped generator is immediately ready for input: 


> wrapped().next('hello!') 
First input: hello! 


The normal generator needs an extra next () until it is ready for input: 
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> let gen0bj = normal(); 

> gen0bj.next() 

{ value: undefined, done: false } 
> genObj.next('hello!') 

First input: hello! 

{ value: 'DONE', done: true } 


22.4.2 yield binds loosely 


yield binds very loosely, so that we don’t have to put its operand in parentheses: 
yield a + b + Cc; 

This is treated as: 

yield (a + b + c); 

Not as: 

(yield a) + b + Cc; 


As a consequence, many operators bind more tightly than yield and you have to put yield in 
parentheses if you want to use it as an operand. For example, you get a SyntaxError if you make an 
unparenthesized yield an operand of plus: 


console.log('Hello' + yield); // SyntaxError 
console.log('Hello' + yield 123); // SyntaxError 


console.log('Hello' + (yield)); // OK 
console. log('Hello' + (yield 123)); // OK 


You do not need parens if yield is a direct argument in a function or method call: 
foo(yield 'a', yield 'b'); 
You also don’t need parens if you use yield on the right-hand side of an assignment: 


let input = yield; 


Generators 378 


22.4.2.1 yield in the ES6 grammar 


The need for parens around yield can be seen in the following grammar rules in the ECMAScript 
6 specification’. These rules describe how expressions are parsed. I list them here from general 
(loose binding, lower precedence) to specific (tight binding, higher precedence). Wherever a certain 
kind of expression is demanded, you can also use more specific ones. The opposite is not true. 
The hierarchy ends with ParenthesizedExpression, which means that you can mention any 
expression anywhere, if you put it in parentheses. 


Expression 
AssignmentExpression 
Expression , AssignmentExpression 
AssignmentExpression 
ConditionalExpression 
YieldExpression 
ArrowFunction 
LeftHandSideExpression = AssignmentExpression 
LeftHandSideExpression AssignmentOperator AssignmentExpression 


AdditiveExpression 
MultiplicativeExpression 
AdditiveExpression + MultiplicativeExpression 
AdditiveExpression - MultiplicativeExpression 
MultiplicativeExpression 
UnaryExpression 
MultiplicativeExpression MultiplicativeOperator UnaryExpression 


PrimaryExpression 
this 
IdentifierReference 
Literal 
ArrayLiteral 
ObjectLiteral 
FunctionExpression 
ClassExpression 
GeneratorExpression 
RegularExpressionLiteral 


*http://www.ecma-international.org/ecma-262/6.0/#sec-expressions 
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TemplateLiteral 

ParenthesizedExpression 
ParenthesizedExpression : 

( Expression ) 


The operands of an AdditiveExpression are an AdditiveExpression anda Multiplicative- 
Expression. Therefore, using a (more specific) ParenthesizedExpression as an operand is OK, 
but using a (more general) YieldExpression isn't. 


22.4.3 return() and throw () 


Let's recap how next (x) works (after the first invocation): 


1. The generator is currently suspended at a yield operator. 

2. Send the value x to that yield, which means that it evaluates to x. 

3. Proceed to the next yield or return: 
e yield x leads to next () returning with { value: x, done: false } 
e return x leads to next() returning with { value: x, done: true } 


return() and throw() work similarly to next (), but they do something different in step 2: 


e return(x) executes return x at the location of yield. 
e throw(x) executes throw x at the location of yield. 


22.4.4 return() terminates the generator 


return() performs a return at the location of the yield that led to the last suspension of the 
generator. Let’s use the following generator function to see how that works. 


functionx genFuncl() { 
try { 
console. log('Started') ; 
yield; // (A) 
} finally { 
console. log('Exiting') ; 


In the following interaction, we first use next() to start the generator and to proceed until the 
yield in line A. Then we return from that location via return(). 
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> let gen0bj1 = genFunc1(); 

> gen0bjl.next() 

Started 

{ value: undefined, done: false } 
> genObji.return('Result') 
Exiting 

{ value: 'Result', done: true } 


22.4.4.1 Preventing termination 


You can prevent return() from terminating the generator if you yield inside the finally clause 
(using a return statement in that clause is also possible): 


functionx genFunc2() { 
try { 
console. log('Started') ; 
yield; 
} finally { 
yield 'Not done, yet!'; 


This time, return() does not exit the generator function. Accordingly, the property done of the 
object it returns is false. 


> let genObj2 = genFunc2(); 
> gen0bj2.next() 
Started 


{ value: undefined, done: false } 


> genObj2.return('Result') 
{ value: 'Not done, yet!', done: false } 


You can invoke next () one more time. Similarly to non-generator functions, the return value of the 
generator function is the value that was queued prior to entering the finally clause. 


> gen0bj2.next() 
{ value: 'Result', done: true } 


22.4.4.2 Returning from a newborn generator 


Returning a value from a newborn generator (that hasn’t started yet) is allowed: 
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> function* genFunc() {} 
> genFunc().return('yes') 
{ value: 'yes', done: true } 


Further reading 


The chapter on iteration has a detailed section on closing iterators and generators. 


22.4.5 throw() signals an error 


throw() throws an exception at the location of the yield that led to the last suspension of the 
generator. Let’s examine how that works via the following generator function. 


functionx genFunc1() { 
try { 
console.log('Started'); 
yield; // (A) 
} catch (error) { 
console. log('Caught: ' + error); 


In the following interaction, we first use next () to start the generator and proceed until the yield 
in line A. Then we throw an exception from that location. 


> let genObj1l = genFunc1(); 


> genObj1.next() 
Started 
{ value: undefined, done: false } 


> gen0bj1.throw(new Error('Problem!')) 
Caught: Error: Problem! 
{ value: undefined, done: true } 


The result of throw() (shown in the last line) stems from us leaving the function with an implicit 
return. 


22.4.5.1 Uncaught exceptions 


If you don’t catch the exception inside the generator, it is thrown by throw(). For example, the 
following generator function does not catch exceptions: 
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functionx genFunc2() { 
console.log('Started'); 
yield; // (A) 


If we use throw() to throw an instance of Error at line A, the method itself throws that error: 


> let genObj2 = genFunc2(); 

> gen0bj2.next() 

Started 

{ value: undefined, done: false } 

> gen0bj2.throw(new Error('Problem! ')) 
Error: Problem! 


22.4.5.2 Throwing from a newborn generator 


Throwing an exception in a newborn generator (that hasn’t started yet) is allowed: 


> function* genFunc() {} 
> genFunc().throw(new Error('Problem!')) 
Error: Problem! 


22.4.6 Example: processing asynchronously pushed data 


The fact that generators-as-observers pause while they wait for input makes them perfect for on- 
demand processing of data that is received asynchronously. The pattern for setting up a chain of 
generators for processing is as follows: 


e Each member of the chain of generators (except the last one) has a parameter target. It 
receives data via yield and sends data via target.next(). 
e The last member of the chain of generators has no parameter target and only receives data. 


The whole chain is prefixed by a non-generator function that makes an asynchronous request and 
pushes the results into the chain of generators via next (). 


As an example, let's chain generators to process a file that is read asynchronously. 


lap) The code of this example is in the file generator-examples/node/readlines.js*. It 
must be executed via babel-node. 


The following code sets up the chain: it contains the generators splitLines, numberLines and 
printLines. Data is pushed into the chain via the non-generator function readFile. 


“https://github.com/rauschma/generator-examples/blob/gh-pages/node/readlines.js 
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readFile(fileName, splitLines(numberLines(printLines()))); 


Pll explain what these functions do when I show their code. 


As previously explained, if generators receive input via yield, the first invocation of next() on 
the generator object doesn’t do anything. That's why I use the previously shown helper function 
coroutine() to create coroutines here. It executes the first next () for us. 


readFile() is the non-generator function that starts everything: 


import {createReadStream} from 'fs'; 


x Creates an asynchronous ReadStream for the file whose name 
x is 'fileName' and feed it to the generator object ‘target’. 


x @see ReadStream https://nodejs.org/api/fs.html#fs_class_fs_readstream 
*/ 
function readFile(fileName, target) { 
let readStream = createReadStream(fileName, 
{ encoding: 'utf8', bufferSize: 1024 }); 
readStream.on('data', buffer => { 
let str = buffer.toString('utf8'); 
target.next(str); 
}); 
readStream.on('end', () => { 
// Signal end of output sequence 
target.return(); 


y); 
The chain of generators starts with splitLines: 
px 


x Turns a sequence of text chunks into a sequence of lines 
x (where lines are separated by newlines) 


*/ 

const splitLines = coroutine(function* (target) { 
let previous = ''; 
try { 


while (true) { 
previous += yield; 
let eolIndex; 
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while ((eolIndex = previous.indexOf('\n')) >= 0) { 
let line = previous.slice(0, eolIndex) ; 
target.next(line); 
previous = previous.slice(eolIndex+1) ; 


} 
} finally { 
// Handle the end of the input sequence 
// (signaled via 'return()') 
if (previous.length > 0) ( 
target.next (previous) ; 
} 
// Signal end of output sequence 
target.return(); 


y); 
Note an important pattern: 


e readFile uses the generator object method return() to signal the end of the sequence of 
chunks that it sends. 

e readFile sends that signal while splitLines is waiting for input via yield, inside an 
infinite loop. return() breaks from that loop. 

e splitLines uses a finally clause to handle the end-of-sequence. 


The next generator is numberLines: 


/[** 

x Prefixes numbers to a sequence of lines 

*/ 

const numberLines = coroutine(functionx (target) { 
try { 


for (let lineNo = 0; ; lineNo++) { 
let line = yield; 
target.next(`${lineNo}: ${line} ); 
} 
} finally { 
// Signal end of output sequence 
target.return(); 


H; 


The last generator is printLines: 
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px 

x Receives a sequence of lines (without newlines) 

x and logs them (adding newlines). 

*/ 

const printLines = coroutine(functionx () { 

while (true) 

let line = yield; 
console. log(line) ; 


Hrs 


H; 


The neat thing about this code is that everything happens lazily (on demand): lines are split, 
numbered and printed as they arrive; we don’t have to wait for all of the text before we can start 
printing. 


22.4.7 yieldx: the full story 


As a rough rule of thumb, yield* performs (the equivalent of) a function call from one generator 
(the caller) to another generator (the callee). 


So far, we have only seen one aspect of yield: it propagates yielded values from the callee to the 
caller. Now that we are interested in generators receiving input, another aspect becomes relevant: 
yield also forwards input received by the caller to the callee. 


Pll first explain the complete semantics of yield» by showing how you'd implemented it in 
JavaScript. Then I give simple examples where input received by the caller via next (), return () 
and throw() is forwarded to the callee. 


The following statement: 
let yieldStarResult = yield» calleeFunc(); 
is roughly equivalent to: 


let yieldStarResult; 


let calleeObj = calleeFunc(); 
let prevReceived = undefined; 
while (true) ( 
try { 
// Forward input previously received 
let {value,done} = calleeObj.next(prevReceived) ; 
if (done) { 
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yieldStarResult = value; 
break; 
} 
prevReceived = yield value; 
} catch (e) { 
// Pretend ‘return’ can be caught like an exception 
if (e instanceof Return) { 
// Forward input received via return() 
callee0bj.return(e.returnedValue) ; 
return e.returnedValue; // “re-throw” 
} else { 
// Forward input received via throw() 
calleeObj.throw(e); // may throw 


To keep things simple, several things are missing in this code: 


e The operand of yield» can be any iterable value. 

e return() and throw() are optional iterator methods. We should only call them if they exist. 

If an exception is received and throw() does not exist, but return() does then return() is 

called (before throwing an exception) to give cal lee0bject the opportunity to clean up. 

e callee0bj can refuse to close, by returning an object whose property done is false. Then 
the caller also has to refuse to close and yield» must continue to iterate. 


22.4.7.1 Example: yield» forwards next () 


The following generator function caller () invokes the generator function callee() via yields. 


function» callee() ( 
console.log('callee: ' + (yield)); 
J 
function» caller() { 
while (true) { 
yield* callee(); 


callee logs values received via next (), which allows us to check whether it receives the value 'a' 
and 'b' that we send to caller. 
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> let callerObj = caller(); 


> callerObj.next() // start 
{ value: undefined, done: false } 


> callerObj.next('a') 
callee: a 
{ value: undefined, done: false } 


> callerObj.next('b') 
callee: b 
{ value: undefined, done: false } 


22.4.7.2 Example: yield» forwards throw() 


Let's use the following code to demonstrate how throw() works while yield is delegating to 
another generator. 


function» callee() ( 


try ( 
yield 'b'; // (A) 
yield 'c'; 


} finally { 
console. log('finally callee'); 


} 
} 
function» caller() { 
try { 
yield 'a'; 
yield* callee(); 
yield 'd'; 
} catch (e) { 
console.log('[caller] ' + e); 
} 
} 


We first create a generator object and advance until line A. 
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> let gen0bj = caller(); 


> gen0bj.next().value 
ta" 
> gen0bj.next().value 
tb? 


In that line, we throw an exception: 


> gen0bj.throw(new Error('Problem! ')) 
finally callee 

[caller] Error: Problem! 

{ value: undefined, done: true } 


callee doesn't catch the exception, which is why it is propagated into caller, where it is logged 
before caller finishes. 


22.4.7.3 Example: yield» forwards return() 


Let's use the following code to demonstrate how return() works while yieldx is delegating to 
another generator. 


function» callee() ( 


try { 
yield 'b'; 
yield 'c'; 


} finally { 
console.log('finally callee'); 


} 
} 
functionx caller() { 
try { 
yield 'a'; 
yield* callee(); 
yield 'd'; 
} finally { 
console.log('finally caller'); 
} 
} 


Destructuring closes an iterator via return() if one doesn’t iterate until the end 
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let [x, y] = caller(); // ['a', 'b'] 


// Output: 
// finally callee 
// finally caller 


Interestingly, the return() is sent to caller and forwarded to callee (which it terminates early), 
but then also terminates cal ler (which is what someone invoking return () would expect). That 
is, return is propagated much like an exception. 


Tip for understanding return() 


In order to understand return(), it helps to ask yourself: what should happen if I copy- 
pasted the code of the callee function into the code of the caller function. 


22.5 Generators as coroutines (cooperative 
multitasking) 


We have seen generators being used as either sources or sinks of data. For many applications, 
it's good practice to strictly separate these two roles, because it keeps things simpler. This section 
describes the full generator interface (which combines both roles) and one use case where both roles 
are needed: cooperative multitasking, where tasks must be able to both send and receive information. 


22.5.1 The full generator interface 


The full interface of generator objects, Generator, handles both output and input: 


interface Generator { 
next(value? : any) : IteratorResult; 
throw(value? : any) : IteratorResult; 
return(value? : any) : IteratorResult; 
} 
interface IteratorResult { 
value : any; 
done : boolean; 


ro cei This interface is described in the spec in the section “Properties of Generator Prototype”. 


+ 


"http://www.ecma-international.org/ecma-262/6.0/*sec-properties-of-generator-prototype 
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The interface Generator combines two interfaces that we have seen previously: Iterator for 


output and Observer for input. 


interface Iterator { // data producer 
next() : IteratorResult; 
return?(value? : any) : IteratorResult; 


interface Observer { // data consumer 
next(value? : any) : void; 
return(value? : any) : void; 
throw(error) : void; 


22.5.2 Cooperative multitasking 


Cooperative multitasking is an application of generators where we need them to handle both output 
and input. Before we get into how that works, let's first review the current state of parallelism in 


JavaScript. 


JavaScript runs in a single process. There are two ways in which this limitation is being abolished: 


e Multiprocessing: Web Workers let you run JavaScript in multiple processes. Shared access to 
data is one of the biggest pitfalls of multiprocessing. Web Workers avoid it by not sharing any 
data. That is, if you want a Web Worker to have a piece of data, you must send it a copy or 


transfer your data to it (after which you can't access it anymore). 


e Cooperative multitasking: There are various patterns and libraries that experiment with 
cooperative multitasking. Multiple tasks are run, but only one at a time. Each task must 
explicitly suspend itself, giving it full control over when a task switch happens. In these 
experiments, data is often shared between tasks. But due to explicit suspension, there are 


few risks. 


Two use cases benefit from cooperative multitasking, because they involve control flows that are 


mostly sequential, anyway, with occasional pauses: 


e Streams: A task sequentially processes a stream of data and pauses if there is no data available. 
— For binary streams, WHATWG is currently working on a standard proposal‘ that is based 


on callbacks and Promises. 


- For streams of data, Communicating Sequential Processes (CSP) are an interesting 


solution. A generator-based CSP library is covered later in this chapter. 


*https://streams.spec.whatwg.org/ 
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e Asynchronous computations: A task blocks (pauses) until it receives the result of a long- 
running computation. 
— In JavaScript, Promises have become a popular way of handling asynchronous compu- 
tations. Support for them is included in ES6. The next section explains how generators 
can make using Promises simpler. 


22.5.2.1 Simplifying asynchronous computations via generators 


Several Promise-based libraries simplify asynchronous code via generators. Generators are ideal as 
clients of Promises, because they can be suspended until a result arrives. 


The following example demonstrates what that looks like if one uses the library co’ by TJ. 
Holowaychuk. We need two libraries (if we run Node.js code via babel-node): 


require('isomorphic-fetch'); // polyfill 
let co = require('co'); 


co is the actual library for cooperative multitasking, isomorphic- fetch is a polyfill for the new 
Promise-based fetch API (a replacement of XMLHttpRequest; read “That's so fetch!*” by Jake 
Archibald for more information). fetch makes it easy to write a function getFile that returns 
the text of a file at a url via a Promise: 


function getFile(url) { 
return fetch(url) 
.then (request => request.text()); 


We now have all the ingredients to use co. The following task reads the texts of two files, parses the 
JSON inside them and logs the result. 


co(functionx () { 
try { 

let [croftStr, bondStr] = yield Promise.all([ // (A) 
getFile('http://localhost:8000/croft.json'), 
getFile('http://localhost:8000/bond.json'), 

1); 

let croftJson = JSON.parse(croftStr) ; 

let bondJson = JSON.parse(bondStr) ; 


console. log(croftJson) ; 


"https://github.com/tj/co 
*http://jakearchibald.com/2015/thats-so-fetch/ 
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console. log(bondJson) ; 
} catch (e) { 
console.log('Failure to read: ' + e); 


}); 


Note how nicely synchronous this code looks, even though it makes an asynchronous call in line 
A. A generator-as-task makes an async call by yielding a Promise to the scheduler function co. The 
yielding pauses the generator. Once the Promise returns a result, the scheduler resumes the generator 
by passing it the result via next (). A simple version of co looks as follows. 


function co(genFunc) { 
let gen0bj = genFunc(); 
run(); 


function run(promiseResult = undefined) { 
let {value,done} = genObj.next(promiseResult) ; 
if (!done) { 
// A Promise was yielded 
value 
.then(result => run(result)) 
.catch(error => { 
genObj.throw(error) ; 


}); 


22.5.3 The limitations of cooperative multitasking via generators 


Coroutines are cooperatively multitasked tasks that have no limitations: Inside a coroutine, any 
function can suspend the whole coroutine (the function activation itself, the activation of the 
function’s caller, the caller’s caller, etc.). 


In contrast, you can only suspend a generator from directly within a generator and only the current 
function activation is suspended. Due to these limitations, generators are occasionally called shallow 
coroutines [3]. 


22.5.3.1 The benefits of the limitations of generators 


The limitations of generators have two main benefits: 
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e Generators are compatible with event loops, which provide simple cooperative multitasking 
in browsers. Pll explain the details momentarily. 

e Generators are relatively easy to implement, because only a single function activation needs 
to be suspended and because browsers can continue to use event loops. 


JavaScript already has a very simple style of cooperative multitasking: the event loop, which 
schedules the execution of tasks in a queue. Each task is started by calling a function and finished 
once that function is finished. Events, setTimeout () and other mechanisms add tasks to the queue. 


This explanation of the event loop is a simplification that is good enough for now. If you 
are interested in details, consult the chapter on asynchronous programming. 


This style of multitasking makes one important guarantee: run to completion; every function can rely 
on not being interrupted by another task until it is finished. Functions become transactions and can 
perform complete algorithms without anyone seeing the data they operate on in an itermediate state. 
Concurrent access to shared data makes multitasking complicated and is not allowed by JavaScript’s 
concurrency model. That’s why run to completion is a good thing. 


Alas, coroutines prevent run to completion, because any function could suspend its caller. For 
example, the following algorithm consists of multiple steps: 


stepl(sharedData) ; 
step2(sharedData) ; 
lastStep(sharedData); 


If step2 was to suspend the algorithm, other tasks could run before the last step of the algorithm is 
performed. Those tasks could contain other parts of the application which would see sharedData 
in an unfinished state. Generators preserve run to completion, they only suspend themselves and 
return to their caller. 


co and similar libraries give you most of the power of coroutines, without their disadvantages: 
e They provide schedulers for tasks defined via generators. 
e Tasks “are” generators and can thus be fully suspended. 


e A recursive (generator) function call is only suspendable if it is done via yield». That gives 
callers control over suspension. 


22.6 Examples of generators 


This section gives several examples of what generators can be used for. 
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lap) The following GitHub repository contains the example code: generator-examples” 


22.6.1 Implementing iterables via generators 


In the chapter on iteration, [implemented several iterables “by hand”. In this section, I use generators, 
instead. 


22.6.1.1 The iterable combinator take() 


take() converts a (potentially infinite) sequence of iterated values into a sequence of length n: 


function» take(n, iterable) { 
for (let x of iterable) { 
if (n <= 0) return; 
n-==; 
yield x; 


The following is an example of using it: 


let arr = ['a', 'b', 'c', 'd']; 

for (let x of take(2, arr)) { 
console. log(x) ; 

} 

// Output: 

// a 

// b 


An implementation of take () without generators is more complicated: 


"https://github.com/rauschma/generator-examples 
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function take(n, iterable) { 
let iter = iterable[Symbol.iterator] (); 
return { 
[Symbol.iterator]() { 
return this; 
a 
next() { 
if (n> 0) { 
n-~3 
return iter.next(); 
} else { 
maybeCLloselIterator (iter); 
return { done: true }; 


le 
return() { 
n = 0; 
maybeCloseIterator (iter); 


}; 
} 
function maybeCloseIterator(iterator) { 
if (typeof iterator.return === 'function') { 
iterator.return(); 


Note that the iterable combinator zip() does not profit much from being implemented via a 
generator, because multiple iterables are involved and for-of can't be used. 


22.6.1.2 Infinite iterables 


naturalNumbers() returns an iterable over all natural numbers: 


function» naturalNumbers() { 
for (let n=0;; n++) { 
yield n; 


This function is often used in conjunction with a combinator: 
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for (let x of take(3, naturalNumbers())) { 
console. log(x) ; 

} 

// Output 

// 0 

if A 

ff 2 


Here is the non-generator implementation, so you can compare: 


function naturalNumbers() { 
let n = 0; 
return { 
[Symbol.iterator]() { 
return this; 


ES 
next() { 

return { value: n++ }; 
} 


22.6.1.3 Array-inspired iterable combinators: map, filter 


Arrays can be transformed via the methods map and filter. Those methods can be generalized to 
have iterables as input and iterables as output. 


22.6.1.3.1 A generalized map() This is the generalized version of map: 


function» map(iterable, mapFunc) { 
for (let x of iterable) { 
yield mapFunc(x); 


map () works with infinite iterables: 


> [...take(4, map(naturalNumbers(), x => x * x))] 
[ 0, Ls 4, 9 ] 


22.6.1.3.2 A generalized filter() This is the generalized version of filter: 
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function» filter(iterable, filterFunc) ( 
for (let x of iterable) { 
if (filterFunc(x)) { 
yield x; 


} 
filter() works with infinite iterables: 


> [...take(4, filter(naturalNumbers(), x => (x % 2) === 0))] 
[ 0, 2, 4, 6 ] 


22.6.2 Generators for lazy evaluation 


The next two examples show how generators can be used to process a stream of characters. 


e The input is a stream of characters. 

e Step 1 — tokenizing (characters — words): The characters are grouped into words, strings that 
match the regular expression /* [A-Za-z0-9]$/. Non-word characters are ignored, but they 
separate words. The input of this step is a stream of characters, the output a stream of words. 

e Step 2 — extracting numbers (words — numbers): only keep words that match the regular 
expression /* [0-9]+$/ and convert them to numbers. 

e Step 3 — adding numbers (numbers — numbers): for every number received, return the total 
received so far. 


The neat thing is that everything is computed lazily (incrementally and on demand): computation 
starts as soon as the first character arrives. For example, we don’t have to wait until we have all 
characters to get the first word. 


22.6.2.1 Lazy pull (generators as iterators) 


Lazy pull with generators works as follows. The three generators implementing steps 1-3 are chained 
as follows: 


addNumbers (extractNumbers (tokenize(CHARS) ) ) 


Each of the chain members pulls data from a source and yields a sequence of items. Processing starts 
with tokenize whose source is the string CHARS. 


22.6.2.1.1 Step 1 — tokenizing The following trick makes the code a bit simpler: the end-of- 
sequence iterator result (whose property done is false) is converted into the sentinel value END_- 
OF_SEQUENCE. 
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px 
x Returns an iterable that transforms the input sequence 
x of characters into an output sequence of words. 
*/ 
function» tokenize(chars) { 
let iterator = chars[Symbol.iterator](); 
let ch; 
do { 
ch = getNextItem(iterator); // (A) 
if (isWordChar(ch)) { 
let word = ''; 
do { 
word += ch; 
ch = getNextItem(iterator); // (B) 
} while (isWordChar(ch)); 
yield word; // (C) 


} 
// Ignore all other characters 
} while (ch !== END_OF_SEQUENCE); 


} 
const END_OF_SEQUENCE = Symbol(); 
function getNextItem(iterator) { 
let {value,done} = iterator.next(); 
return done ? END_OF_SEQUENCE : value; 


} 
function isWordChar(ch) { 

return typeof ch === 'string' && /^[A-Za-z0-9]$/.test(ch); 
} 


How is this generator lazy? When you ask it for a token via next (), it pulls its iterator (lines A 
and B) as often as needed to produce as token and then yields that token (line C). Then it pauses 
until it is again asked for a token. That means that tokenization starts as soon as the first characters 
are available, which is convenient for streams. 


Let’s try out tokenization. Note that the spaces and the dot are non-words. They are ignored, but 
they separate words. We use the fact that strings are iterables over characters (Unicode code points). 
The result of tokenize() is an iterable over words, which we turn into an array via the spread 
operator (...). 


> [...tokenize('2 apples and 5 oranges.')] 
[ "2", *apples*, 'and', '5', “oranges” ] 
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22.6.2.1.2 Step 2- extracting numbers This step is relatively simple, we only yield words that 
contain nothing but digits, after converting them to numbers via Number (). 


px 

x Returns an iterable that filters the input sequence 
x of words and only yields those that are numbers. 

*/ 
function» extractNumbers(words) { 

for (let word of words) { 
if (/*[0-9]+$/.test(word)) { 
yield Number (word); 


You can again see the laziness: If you ask for a number via next (), you get one (via yield) as soon 
as one is encountered in words. 


Let’s extract the numbers from an Array of words: 


> [...extractNumbers(['hello', '123', 'world', '45'])] 
[ 123, 45 ] 


Note that strings are converted to numbers. 


22.6.2.1.3 Step 3 — adding numbers 


px 
x Returns an iterable that contains, for each number in 
x ‘numbers’, the total sum of numbers encountered so far. 
* For example: 7, 4, -1 --> 7, 11, 10 
*/ 
function» addNumbers (numbers) { 
let result = 0; 
for (let n of numbers) { 
result += n; 
yield result; 


Let's try a simple example: 
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> [...addNumbers([5, -2, 12])] 
[ 5, 3, 15 ] 


22.6.2.1.4 Pulling the output On its own, the chain of generator doesn't produce output. We 
need to actively pull the output via the spread operator: 


const CHARS = '2 apples and 5 oranges.'; 
const CHAIN = addNumbers(extractNumbers(tokenize(CHARS) ) ) ; 
console. log([...CHAIN]) ; 

E Ls 7 J 


The helper function logAndYield allows us to examine whether things are indeed computed lazily: 


functionx logAndYield(iterable, prefix='') { 
for (let item of iterable) { 
console. log(prefix + item); 
yield item; 


const CHAIN2 = logAndYield(addNumbers(extractNumbers (tokenize(logAndYield (CHARS) \ 
))) , ka '); 
[...CHAIN2]; 


// Output: 
ff 2 


= 
Sy 
TE E a a e DW 


SS 
SS 
w 
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Ed 
// 
// 
// 
// 
El 
// 
El 


0 0 7 SDS YW Wy O 


The output shows that addNumbers produces a result as soon as the characters '2' and ' ' are 
received. 


22.6.2.2 Lazy push (generators as observables) 


Not much work is needed to convert the previous pull-based algorithm into a push-based one. The 
steps are the same. But instead of finishing via pulling, we start via pushing. 


As previously explained, if generators receive input via yield, the first invocation of next() on 
the generator object doesn’t do anything. That’s why I use the previously shown helper function 
coroutine() to create coroutines here. It executes the first next () for us. 


The following function send() does the pushing. 


px 
x Pushes the items of 'iterable' into ‘sink’, a generator. 
x It uses the generator method “next()* to do so. 
*/ 
function send(iterable, sink) { 

for (let x of iterable) { 

sink.next(x); 
} 


sink.return(); // signal end of stream 


When a generator processes a stream, it needs to be aware of the end of the stream, so that it can clean 
up properly. For pull, we did this via a special end-of-stream sentinel. For push, the end-of-stream 
is signaled via return(). 


Let's test send () via a generator that simply outputs everything it receives: 
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px 
x This generator logs everything that it receives via 'next()”. 
*/ 
const logItems = coroutine(functionx () { 
try { 
while (true) { 
let item = yield; // receive item via `next()` 
console. log(item) ; 
} 
} finally { 
console.log('DONE'); 


});5 
Let's send loglItems () three characters via a string (which is an iterable over Unicode code points). 


> send('abc', logltems()); 
a 

b 

c 

DONE 


22.6.2.2.1 Step 1- tokenize Note how this generator reacts to the end of the stream (as signaled 
via return()) in two finally clauses. We depend on return() being sent to either one of the two 
yields. Otherwise, the generator would never terminate, because the infinite loop starting in line 
A would never terminate. 


px 
x Receives a sequence of characters (via the generator object 
x method `next()`), groups them into words and pushes them 
x into the generator ‘sink’. 
*/ 
const tokenize = coroutine(functionx (sink) { 
try { 
while (true) { // (A) 
let ch = yield; // (B) 
if (isWordChar(ch)) { 
// A word has started 
let word = ''; 
try { 
do { 
word += ch; 
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ch = yield; // (C) 
} while (isWordChar(ch)); 
} finally { 
// The word is finished. 
// We get here if 
// - the loop terminates normally 
// - the loop is terminated via 'return()' in line C 
sink.next(word); // (D) 


} 
// Ignore all other characters 
} 
} finally { 
// We only get here if the infinite loop is terminated 
// via `return()` (in line B or C). 
// Forward `return()` to 'sink' so that it is also 
// aware of the end of stream. 
sink.return(); 


ioe 


function isWordChar(ch) { 
return /“[A-Za-z0-9]$/.test(ch) 3 


This time, the laziness is driven by push: as soon as the generator has received enough characters 
for a word (in line C), it pushes the word into sink (line D). That is, the generator does not wait 
until it has received all characters. 


tokenize() demonstrates that generators work well as implementations of linear state machines. 
In this case, the machine has two states: “inside a word” and “not inside a word”. 


Let’s tokenize a string: 


> send('2 apples and 5 oranges.', tokenize(logltems())); 
2 

apples 

and 

5 

oranges 


22.6.2.2.2 Step 2 — extract numbers This step is straightforward. 


Generators 404 


px 
x Receives a sequence of strings (via the generator object 
x method 'next()') and pushes only those strings to the generator 
x ‘sink’ that are “numbers” (consist only of decimal digits). 
*/ 
const extractNumbers = coroutine(functionx (sink) { 
try { 
while (true) { 
let word = yield; 
if (/*[0-9]+S/.test(word)) { 
sink.next (Number (word) ); 


} 

} finally { 
// Only reached via `return()`, forward. 
sink.return(); 


}); 


Things are again lazy: as soon as as number is encountered, it is pushed to sink. 


Let's extract the numbers from an Array of words: 


> send(['hello', '123', 'world', '45'], extractNumbers(logltems())); 
123 

45 

DONE 


Note that the input is a sequence of strings, while the output is a sequence of numbers. 


22.6.2.2.3 Step 3 — add numbers This time, we react to the end of the stream by pushing a single 
value and then closing the sink. 


px 
x Receives a sequence of numbers (via the generator object 
x method 'next()'). For each number, it pushes the total sum 
x so far to the generator ‘sink’. 
x / 
const addNumbers = coroutine(functionx (sink) { 
let sum = 0; 
try { 
while (true) { 
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sum += yield; 
sink.next(sum) ; 
} 
} finally { 
// We received an end-of-stream 
sink.return(); // signal end of stream 


y); 
Let's try out this generator: 


> send([5, -2, 12], addNumbers(logItems())) 5; 
5 

3 

15 

DONE 


22.6.2.2.4 Pushing the input The chain of generators starts with tokenize and ends with 
logItems, which logs everything it receives. We push a sequence of characters into the chain via 
send: 


const INPUT = '2 apples and 5 oranges.'; 
const CHAIN = tokenize(extractNumbers(addNumbers(logltems()))); 
send(INPUT, CHAIN); 


// Output 
(7 2 
fj T 

// DONE 


The following code proves that processing really happens lazily: 


const CHAIN2 = tokenize(extractNumbers (addNumbers(logItems({ prefix: '-> ' 3)))); 
send(INPUT, CHAIN2, { log: true }); 


// Output 
jf 2 

// 

ff => 2 
// a 

// p 
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Ed 
// 
iy 
// 
pi 
fi 
// n 
// d 
f4 

// 5 
// 

// -> 7 
fd 


no 7D 


w 


= 
= 
Yn 00M >5Qy”z53./0o 


// DONE 


The output shows that addNumbers produces a result as soon as the characters '2' and ' ' are 
pushed. 


22.6.3 Cooperative multi-tasking via generators 


22.6.3.1 Pausing long-running tasks 


In this example, we create a counter that is displayed on a web page. We improve an initial version 
until we have a cooperatively multitasked version that doesn’t block the main thread and the user 
interface. 


This is the part of the web page in which the counter should be displayed: 


<body> 
Counter: <span id="counter"></span> 
</body> 


This function displays a counter that counts up forever”: 


*°Or rather, the function counts up until the number start overflows and becomes Infinity, at which point it doesn't change, anymore. 
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function countUp(start = 0) { 
const counterSpan = document.querySelector('#counter'); 
while (true) { 
counterSpan.textContent = String(start) ; 
start++; 


If you ran this function, it would completely block the user interface thread in which it runs and its 
tab would become unresponsive. 


Let's implement the same functionality via a generator that periodically pauses via yield (a 
scheduling function for running this generator is shown later): 


functionx countUp(start = 0) ( 
const counterSpan = document.querySelector('#counter'); 
while (true) { 
counterSpan.textContent = String(start) ; 
start++; 
yield; // pause 


Let's add one small improvement. We move the update of the user interface to another generator, 
displayCounter, which we call via yield». As it is a generator, it can also take care of pausing. 


functionx countUp(start = 0) ( 
while (true) ( 
start++; 
yield* displayCounter(start); 


t 

function» displayCounter(counter) ( 
const counterSpan = document.querySelector('tcounter'); 
counterSpan.textContent = String(counter) ; 
yield; // pause 


Lastly, this is a scheduling function that we can use to run countUp(). Each execution step of the 
generator is handled by a separate task, which is created via setTimeout (). That means that the 
user interface can schedule other tasks in between and will remain responsive. 
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function run(generatorObject) { 
if (!generatorObject.next().done) { 
// Add a new task to the event queue 
setTimeout (function () { 
run(generatorObject) ; 
}, 1000); 


} 


With the help of run, we get a (nearly) infinite count-up that doesn’t block the user interface: 


run(countUp()); 


lap) You can run this example online”. 


22.6.3.2 Cooperative multitasking with generators and Node.js-style callbacks 


If you call a generator function (or method), it does not have access to its generator object; its this is 
the this it would have if it were a non-generator function. A work-around is to pass the generator 
object into the generator function via yield. 


The following Node.js script uses this technique, but wraps the generator object in a callback (next, 
line A). It must be run via babel-node. 


import {readFile} from 'fs'; 
let fileNames = process.argv.slice(2); 


run(functionx () { 
let next = yield; 
for (let f of fileNames) { 
let contents = yield readFile(f, { encoding: 'utf8' }, next); 
console. log('##### ' + f); 
console. log(contents) ; 


H; 


In line A, we get a callback that we can use with functions that follow Node.js callback conventions. 
The callback uses the generator object to wake up the generator, as you can see in the implementation 
of run(): 


“https://rauschma.github.io/generator-examples/nonblocking-counter/ 
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function run(generatorFunction) { 
let generatorObject = generatorFunction() ; 


// Step 1: Proceed to first ‘yield’ 
generatorObject.next(); 


// Step 2: Pass in a function that the generator can use as a callback 
function nextFunction(error, result) ( 
if (error) { 
generatorObject.throw(error) ; 
} else { 
generatorObject.next(result) ; 


} 


generatorObject.next(nextFunction) ; 


// Subsequent invocations of 'next()' are triggered by 'nextFunction' 


22.6.3.3 Communicating Sequential Processes (CSP) 


The library js-csp” brings Communicating Sequential Processes (CSP) to JavaScript, a style of 
cooperative multitasking that is similar to ClojureScript’s core.async and Go's goroutines. js-csp 
has two abstractions: 


e Processes: are cooperatively multitasked tasks and implemented by handing a generator 
function to the scheduling function go(). 

e Channels: are queues for communication between processes. Channels are created by calling 
chan(). 


As an example, let’s use CSP to handle DOM events, in a manner reminiscent of Functional Reactive 
Programming. The following code uses the function listen() (which is shown later) to create a 
channel that outputs mousemove events. It then continuously retrieves the output via take, inside 
an infinite loop. Thanks to yield, the process blocks until the channel has output. 


“https://github.com/ubolonton/js-csp 
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import csp from 'js-csp'; 


csp.go(functionx () { 
let element = document.querySelector('tuiElement1'); 
let channel = listen(element, 'mousemove'); 
while (true) ( 
let event = yield csp.take(channel); 
let x = event.layerX || event.clientX; 
let y = event.layerY || event.clientY; 
element.textContent = `${x}, ${y} ; 


}); 
listen() is implemented as follows. 


function listen(element, type) { 
let channel = csp.chan(); 
element.addEventListener (type, 
event => { 
csp.putAsync(channel, event); 
}); 


return channel; 


A This example is taken from the blog post “Taming the Asynchronous Beast with CSP 
Es Channels in JavaScript?” by James Long. Consult this blog post for more information on 
CSP. 


22.7 Inheritance within the iteration API (including 
generators) 


This is a diagram of how various objects are connected in ECMAScript 6 (it is based on Allen Wirf- 
Brock’s diagram'* in the ECMAScript specification): 


http://jlongster.com/Taming-the- Asynchronous-Beast-with-CSP-in-JavaScript 
“http://www.ecma-international.org/ecma-262/6.0/+*sec-generatorfunction-objects 


Generators 


Function 


prototype 


(GeneratorFunction) 


Legend: 


411 


Object.prototype 


(IteratorPrototype) 
[Symbol.iterator]() 


Function.prototype 


(Generator) prototype (Generator).prototype 
AA A next() 


return() 
throw 


g1.prototype 


e The white (hollow) arrows express the has-prototype relationship (inheritance) between 
objects. In other words: a white arrow from x to y means that Object. getPrototypeOf (x) 


p= y. 


e Parentheses indicate that an object exists, but is not accessible via a global variable. 
+ An instanceof arrow from x to y means that x instanceof y. 

— Remember that o instanceof C is equivalent to C. prototype. isPrototypeOf(o). 
+ A prototype arrow from x to y means that x.prototype === y. 


The diagram reveals two interesting facts: 


First, a generator function g works very much like a constructor (you can even invoke it via new, 
which has basically the same effect as calling it): The generator objects it creates are instances of it, 
methods added to g. prototype become prototype methods, etc.: 
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> functionx g() {} 

> g.prototype.hello = function () { return 'hi!'); 
> let obj = g(); 

> obj instanceof g 

true 

> obj.hello() 

le 


Second, if you want to make methods available for all generator objects, it's best to add them to 
(Generator .object). One way of accessing that object is as follows: 


> let Generator_prototype = Object.getPrototype0f (functionx () (3) .prototype; 
> Generator_prototype.hello = function () { return 'hi!'}; 

> let generatorObject = (functionx () {1} 0; 

> generatorObject.hello() 

"hil! 


22.7.1 IteratorPrototype 


There isno (Iterator) in the diagram, because no such object exists. But, given how instanceof 
works and because (IteratorPrototype) is a prototype of g1(), you could still say that g1() is 
an instance of Iterator. 


All iterators in ES6 have (IteratorPrototype) in their prototype chain. That object is iterable, 
because it has the following method. Therefore, all ES6 iterators are iterable (as a consequence, you 
can apply for-of etc. to them). 


[Symbol.iterator]() 4 
return this; 


The specification recommends to use the following code to access (IteratorPrototype): 


const proto = Object.getPrototypeOf.bind(Object) ; 
let IteratorPrototype = proto(proto([][Symbol.iterator]())); 


You could also use: 
let IteratorPrototype = proto(proto(functionx () {}.prototype) ); 


Quoting the ECMAScript 6 specification: 
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ECMAScript code may also define objects that inherit from IteratorPrototype. 
The IteratorPrototype object provides a place where additional methods that are 
applicable to all iterator objects may be added. 


IteratorPrototype will probably become directly accessible in an upcoming version of EC- 
MAScript and contain tool methods such as map() and filter () (source””). 


22.7.2 The value of this in generators 


A generator function combines two concerns: 


1. Itis a function that sets up and returns a generator object. 
2. It contains the code that the generator object steps through. 


That's why it's not immediately obvious what the value of this should be inside a generator. 


In function calls and method calls, this is what it would be if gen() wasn't a generator function, 
but a normal function: 


functionx gen() ( 
‘use strict'; // just in case 
yield this; 


// Retrieve the yielded value via destructuring 
let [functionThis] = gen(); 
console.log(functionThis); // undefined 


let obj = { method: gen }; 
let [methodThis] = obj.method(); 
console. log(methodThis === obj); // true 


If you access this in a generator that was invoked via new, you get a ReferenceError (source: 
ES6 spec**): 


https://github.com/rwaldron/tc39-notes/blob/master/es6/2014-07/jul-30.md#47-revisit-comprehension-decision-from-last-meeting 
*http://www.ecma-international.org/ecma-262/6.0/#sec-generator-function- definitions-runtime-semantics-evaluatebody 
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functionx gen() ( 
console.log(this); // ReferenceError 


} 


new gen(); 


A work-around is to wrap the generator in a normal function that hands the generator its generator 
object via next (). That means that the generator must use its first yield to retrieve its generator 
object: 


let generatorObject = yield; 


22.8 Style consideration: whitespace before and after 
the asterisk 


Reasonable - and legal — variations of formatting the asterisk are: 


e A space before and after it: 
function * foo(x, y) { +} 
e A space before it: 
function xfoo(x, y) 1 ::: } 
e A space after it: 
function» foo(x, y) 1 °: } 
e No whitespace before and after it: 
functionxfoo(x, y) 1 =+ } 


Let's figure out which of these variations make sense for which constructs and why. 


22.8.1 Generator function declarations and expressions 


Here, the star is only used because generator (or something similar) isn't available as a keyword. 
If it were, then a generator function declaration would look like this: 


generator foo(x, y) 1 


} 


Instead of generator, ECMAScript 6 marks the function keyword with an asterisk. Thus, 
function» can be seen as a synonym for generator, which suggests writing generator function 
declarations as follows. 
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function» foo(x, y) { 


Anonymous generator function expressions would be formatted like this: 


const foo = functionx (x, y) ( 


22.8.2 Generator method definitions 


When writing generator method definitions, I recommend to format the asterisk as follows. 


let obj = { 
* generatorMethod(x, y) { 


$ 


There are three arguments in favor of writing a space after the asterisk. 


First, the asterisk shouldn't be part of the method name. On one hand, it isn’t part of the name of 
a generator function. On the other hand, the asterisk is only mentioned when defining a generator, 
not when using it. 


Second, a generator method definition is an abbreviation for the following syntax. (To make my 
point, ’m redundantly giving the function expression a name, too.) 


let obj = £ 
generatorMethod: function* generatorMethod(x, y) { 


}; 
If method definitions are about omitting the function keyword then the asterisk should be followed 


by a space. 


Third, generator method definitions are syntactically similar to getters and setters (which are already 
available in ECMAScript 5): 
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let obj = { 
get foo() { 
t 


set foo(value) { 


}; 


The keywords get and set can be seen as modifiers of a normal method definition. Arguably, an 
asterisk is also such a modifier. 


22.8.3 Formatting recursive yield 


The following is an example of a generator function yielding its own yielded values recursively: 


function» foo(x) { 


yieldx foo(x - 1); 


The asterisk marks a different kind of yield operator, which is why the above way of writing it 
makes sense. 


22.8.4 Documenting generator functions and methods 


Kyle Simpson (@getify) proposed something interesting: Given that we often append parentheses 
when we write about functions and methods such as Math . max ( ) , wouldn't it make sense to prepend 
an asterisk when writing about generator functions and methods? For example: should we write 
*foo() to refer to the generator function in the previous subsection? Let me argue against that. 


When it comes to writing a function that returns an iterable, a generator is only one of the several 
options. I think it is better to not give away this implementation detail via marked function names. 


Furthermore, you don't use the asterisk when calling a generator function, but you do use 
parentheses. 


Lastly, the asterisk doesn't provide useful information — yieldx can also be used with functions that 
return an iterable. But it may make sense to mark the names of functions and methods (including 
generators) that return iterables. For example, via the suffix Iter. 
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22.9 Conclusion 


I hope that this chapter convinced you that generators are a useful and versatile tool. 


I like that generators let you implement cooperatively multitasked tasks that block while making 
asynchronous function calls. In my opinion that’s the right mental model for async calls. Hopefully, 
JavaScript goes further in this direction in the future. 


22.10 Further reading 


Sources of this chapter: 
[1] “Async Generator Proposal'”” by Jafar Husain 
[2] “A Curious Course on Coroutines and Concurrency**” by David Beazley 


[3] “Why coroutines won't work on the web*” by David Herman 


https://github.com/jhusain/asyncgenerator 
“http://www.dabeaz.com/coroutines/ 
“http://calculist.org/blog/2011/12/14/why-coroutines-wont-work-on-the-web/ 
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23. New regular expression features 


This chapter explains new regular expression features in ECMAScript 6. It helps if you are familiar 
with ES5 regular expression features and Unicode. Consult the following two chapters of “Speaking 
JavaScript” if necessary: 


e “Regular Expressions!” 
e “Unicode and JavaScript?” 


23.1 Overview 


The following regular expression features are new in ECMAScript 6: 


The new flag /y (sticky) anchors each match of a regular expression to the end of the previous 

match. 

e The new flag /u (unicode) handles surrogate pairs (such as \uD83D\uDE80) as code points 
and lets you use Unicode code point escapes (such as \u{1F680}) in regular expressions. 

e The new data property flags gives you access to the flags of a regular expression, just like 

source already gives you access to the pattern in ES5: 


> /abc/ig.source // ES5 
‘abc' 
> /abc/ig.flags // ES6 
'gi' 


e You can use the constructor RegExp() to make a copy of a regular expression: 


> new RegExp(/abc/ig).flags 

‘gi! 

> new RegExp(/abc/ig, 'i').flags // change flags 
rar! 


*http://speakingjs.com/es5/ch19.html 
*http://speakingjs.com/es5/ch24.html 
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23.2 New flag / y (sticky) 


The new flag /y changes two things while matching a regular expression re against a string: 


e Anchored to re.lastIndex: The match must start at re.lastIndex (the index after the 
previous match). This behavior is similar to the * anchor, but with that anchor, matches must 
always start at index 0. 

e Match repeatedly: If a match was found, re. LastIndex is set to the index after the match. 
This behavior is similar to the /g flag. Like /g, /y is normally used to match multiple times. 


The main use case for this matching behavior is tokenizing, where you want each match to 
immediately follow its predecessor. An example of tokenizing via a sticky regular expression and 
exec() is given later. 


Let’s look at how various regular expression operations react to the /y flag. The following tables 
give an overview. IIl provide more details afterwards. 


Methods of regular expressions (re is the regular expression that a method is invoked on): 


Flags Start matching Anchored to Result if match No match  re.lastindex 


exec() - 0 = Match object null unchanged 
/g re.lastIndex - Match object null index after match 
ly re.lastIndex re.lastIndex Match object null index after match 
/gy re.lastIndex re.lastIndex Match object null index after match 
test() (Any) (like exec()) (like exec()) true false (like exec()) 


Methods of strings (str is the string that a method is invoked on, r is the regular expression 
parameter): 


Flags Start matching Anchored to Result if match No match  r.lastindex 
search() -,/g 0 7 Index of match -1 unchanged 
/y, lgy 0 0 Index of match -1 unchanged 
match)  - 0 = Match object null unchanged 
ly r.lastIndex  r.lastIndex Match object null index after 
match 
/g After prev. = Array with matches null 0 
match (loop) 
/gy After prev. After prev. Array with matches null 0 
match (loop) match 
split() -,/g After prev. = Array with strings [str] unchanged 
match (loop) between matches 
/y,/gy After prev. After prev. Arr. w/ empty strings [str] unchanged 
match (loop) match between matches 


replace() - 0 = First match replaced No repl. unchanged 
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Flags Start matching Anchored to Result if match No match  r.lastindex 

ly 0 0 First match replaced No repl. unchanged 

/g After prev. = All matches replaced No repl. unchanged 
match (loop) 

/gy After prev. After prev. All matches replaced No repl. unchanged 
match (loop) match 


23.2.1 RegExp.prototype.exec(str) 


If /g is not set, matching always starts at the beginning, but skips ahead until a match is found. 
REGEX. lastIndex is not changed. 


const REGEX = /a/; 


REGEX.lastIndex = 7; // ignored 

const match = REGEX.exec('xaxa'); 

console. log(match.index); // 1 

console. lLog(REGEX. LastIndex); // 7 (unchanged) 


If /g is set, matching starts at REGEX.lastIndex and skips ahead until a match is found. 
REGEX. LastIndex is set to the position after the match. That means that you receive all matches if 
you loop until exec() returns null. 


const REGEX = /a/g; 


REGEX. lastIndex = 2; 

const match = REGEX.exec('xaxa'); 

console. log(match. index); // 3 

console. lLog(REGEX. LastIndex); // 4 (updated) 


// No match at index 4 or later 
console. lLog(REGEX.exec('xaxa')); // null 


If only /y is set, matching starts at REGEX. Last Index and is anchored to that position (no skipping 
ahead until a match is found). REGEX. lastIndex is updated similarly to when /g is set. 
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const REGEX = /a/y; 


// No match at index 2 
REGEX. lastIndex = 2; 
console. log(REGEX.exec('xaxa')); // null 


// Match at index 3 

REGEX. lastIndex = 3; 

const match = REGEX.exec('xaxa'); 
console. log(match. index); // 3 
console.log(REGEX.lastIndex); // 4 


Setting both /y and /g is the same as only setting /y. 


23.2.2 RegExp.prototype.test(str) 


test () works the same as exec (), but it returns true or false (instead of a match object or null) 
when matching succeeds or fails: 


const REGEX = /a/y; 


REGEX. lastIndex = 2; 
console. log(REGEX.test('xaxa')); // false 


REGEX. lastIndex = 3; 


console. lLog(REGEX.test('xaxa'))3 // true 
console. lLog(REGEX. LastIndex); // 4 


23.2.3 String.prototype.search(regex) 
search() ignores the flag /g and lastIndex (which is not changed, either). Starting at the 


beginning of the string, it looks for the first match and returns its index (or -1 if there was no 
match): 


const REGEX = /a/; 


REGEX. lastIndex = 2; // ignored 
console. log('xaxa'.search(REGEX)); // 1 


If you set the flag /y, LastIndex is still ignored, but the regular expression is now anchored to 
index 0. 
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const REGEX = /a/y; 


REGEX.lastIndex = 1; // ignored 
console.log('xaxa'.search(REGEX)); // -1 (no match) 


23.2.4 String.prototype.match(regex) 


match () has two modes: 


e If /g is not set, it works like exec (). 
e If /g is set, it returns an Array with the string parts that matched, or null. 


If the flag /g is not set, match() captures groups like exec(): 


const REGEX = /a/; 


REGEX. LastIndex = 7; // ignored 
console. log('xaxa'.match(REGEX) .index); // 1 
console. Log(REGEX.lastIndex); // 7 (unchanged) 


const REGEX = /a/y; 


REGEX. LastIndex = 2; 
console. log('xaxa'.match(REGEX)); // null 


REGEX. LastIndex = 3; 
console. log('xaxa'.match(REGEX) .index); // 3 
console. Log(REGEX.lastIndex); // 4 


If only the flag /g is set then match() returns all matching substrings in an Array (or null). 
Matching always starts at position 0. 


const REGEX = /alb/g; 

REGEX. lastIndex = 7; 
console.log('xaxb'.match(REGEX)); // ['a', 'b'] 
console.log(REGEX.lastIndex); // 0 


If you additionally set the flag /y, then matching is still performed repeatedly, while anchoring the 
regular expression to the index after the previous match (or 0). 
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const REGEX = /a|b/gy; 


REGEX. lastIndex = 0; // ignored 
console. log('xab'.match(REGEX)); // null 
REGEX. lastIndex = 1; // ignored 
console. log('xab'!.match(REGEX)); // null 


console. log('ab'.match(REGEX)); // ['a', 'b'] 
console.log('axb'.match(REGEX)); // ['a'] 


23.2.5 String.prototype.split(separator, limit) 


The complete details of split() are explained in Speaking JavaScript’. 
For ES6, it is interesting to see how things change if you use the flag /y. 
With /y, the string must start with a separator: 


> 'x##'.split(/#/y) // no match 
[ 'x##' ] 

> '##x'.split(/#/y) // 2 matches 
[ ee uae Ue a ] 


Subsequent separators are only recognized if they immediately follow the first separator: 


> '#x#'.split(/#/y) // 1 match 


[ ue Is! ] 
> '##'.split(/#/y) // 2 matches 
[ ves aan tt ] 


That means that the string before the first separator and the strings between separators are always 
empty. 
As usual, you can use groups to put parts of the separators into the result array: 


> '##'.split(/(#)/y) 
[ A A A ] 


23.2.6 String.prototype.replace(search, 
replacement) 


Without the flag /g, replace() only replaces the first match: 


*http://speakingjs.com/es5/ch19.html#String. prototype.match 
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const REGEX = /a/; 


// One match 
console.log('xaxa'.replace(REGEX, '-')); // 'x-xa' 


If only / y is set, you also get at most one match, but that match is always anchored to the beginning 
of the string. lastIndex is ignored and unchanged. 


const REGEX = /a/y; 

// Anchored to beginning of string, no match 
REGEX.lastIndex = 1; // ignored 
console.log('xaxa'.replace(REGEX, '-')); // 'xaxa' 


console. log(REGEX.lastIndex); // 1 (unchanged) 


// One match 
console.log('axa'.replace(REGEX, '-')); // '-xa' 


With /g set, replace() replaces all matches: 


const REGEX = /a/g; 


// Multiple matches 
console.log('xaxa'.replace(REGEX, '-')); // 'x-x-' 


With / gy set, replace () replaces all matches, but each match is anchored to the end of the previous 
match: 


const REGEX = /a/gy; 


// Multiple matches 
console. log('aaxa'.replace(REGEX, '-')); // '--xa' 


The parameter replacement can also be a function, consult “Speaking JavaScript” for details*. 


23.2.7 Example: using sticky matching for tokenizing 


The main use case for sticky matching is tokenizing, turning a text into a sequence of tokens. One 
important trait about tokenizing is that tokens are fragments of the text and that there must be no 
gaps between them. Therefore, sticky matching is perfect here. 


*http://speakingjs.com/es5/ch19.html*String.prototype.replace 
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function tokenize(TOKEN_REGEX, str) { 
let result = []; 
let match; 
while (match = TOKEN_REGEX.exec(str)) ( 
result.pushí(match[1]); 
} 


return result; 


const TOKEN_GY = /\s*(\+|[0-9]+)\s*/gy; 
const TOKEN_G = /\sx*(\+|[0-9]+)\s*/g; 


In a legal sequence of tokens, sticky matching and non-sticky matching produce the same output: 


tokenize(TOKEN_GY, '3 + 4') 
PRE Eae t4! ] 
tokenize(TOKEN_G, '3 + 4') 
U2) 5 Mae Ya" ] 


av m Vv 


If, however, there is non-token text in the string then sticky matching stops tokenizing, while non- 
sticky matching skips the non-token text: 


tokenize(TOKEN_GY, '3x + 4') 
"3" ] 

tokenize(TOKEN_G, '3x + 4') 
130 ; 14! ; T4! ] 


ric E a Y 


The behavior of sticky matching during tokenizing helps with error handling. 


23.2.8 Example: manually implementing sticky matching 


If you wanted to manually implement sticky matching, you'd do it as follows: The function 
execSticky() works like RegExp.prototype.exec() in sticky mode. 
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function execSticky(regex, str) { 
// Anchor the regex to the beginning of the string 
let matchSource = regex.source; 
if (!matchSource.startswith('’')) { 
matchSource = '^' + matchSource; 
} 
// Ensure that instance property 'lastIndex' is updated 
let matchFlags = regex.flags; // ES6 feature! 
if (!regex.global) { 
matchFlags = matchFlags + 'g'; 
} 


let matchRegex = new RegExp(matchSource, matchFlags); 


// Ensure we start matching 'str' at `regex.lastIndex` 
const matchOffset = regex.lastIndex; 

const matchStr = str.slice(matchOffset); 

let match = matchRegex.exec(matchStr); 


// Translate indices from 'matchStr' to `str` 

regex. lastIndex = matchRegex.lastIndex + matchOffset; 
match.index = match.index + matchOffset; 

return match; 


23.3 New flag /u (unicode) 


The flag /u switches on a special Unicode mode for a regular expression. That mode has two features: 


1. You can use Unicode code point escape sequences such as \u{1F42A} for specifying char- 
acters via code points. Normal Unicode escapes such as \u03B1 only have a range of four 
hexadecimal digits (which equals the basic multilingual plane). 

2. “characters” in the regular expression pattern and the string are code points (not UTF-16 code 
units). Code units are converted into code points. 


A section in the chapter on Unicode has more information on escape sequences. Pll explain the 
consequences of feature 2 next. Instead of Unicode code point escapes (e.g., \u{1F680}), I’m using 
two UTF-16 code units (e.g., \uD83D\uDE80). That makes it clear that surrogate pairs are grouped 
in Unicode mode and works in both Unicode mode and non-Unicode mode. 
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> '\u{1F680}' === '\uD83D\uDE80' // code point vs. surrogate pairs 
true 


23.3.1 Consequence: lone surrogates in the regular expression 
only match lone surrogates 


In non-Unicode mode, a lone surrogate in a regular expression is even found inside (surrogate pairs 
encoding) code points: 


> /\uD83D/.test('\uD83D\uDC2A' ) 
true 


In Unicode mode, surrogate pairs become atomic units and lone surrogates are not found “inside” 
them: 


> /\uD83D/u.test('\uD83D\uDC2A' ) 
false 


Actual lone surrogate are still found: 


> /\uD83D/u.test('\uD83D \uD83D\uDC2A' ) 
true 
> /\uD83D/u.test('\uD83D\uDC2A \uD83D' ) 
true 


23.3.2 Consequence: you can put code points in character classes 


In Unicode mode, you can put code points into character classes and they won't be interpreted as 
two characters, anymore. 


> /A[\uD83D\uDC2A]$/u.test('\uD83D\uDC2A' ) 
true 

> /A[\uD83D\uDC2A]$/.test('\uD83D\uDC2A' ) 
false 


> /1*[1uD83D1uDC2A]5/u.test('1uD83D') 
false 

> /A[\uD83D\uDC2A]$/.test('\uD83D') 
true 


23.3.3 Consequence: the dot operator (.) matches code points, 
not code units 


In Unicode mode, the dot operator matches code points (one or two code units). In non-Unicode 
mode, it matches single code units. For example: 
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'"NuD83D1uDE80' .match(/./gu). length 


'"NuD83D1uDE80' .match(/./g).length 


N VF v 


23.3.4 Consequence: quantifiers apply to code points, not code 
units 


In Unicode mode, quantifiers apply to code points (one or two code units). In non-Unicode mode, 
they apply to single code units. For example: 


> /\uD83D\uDE80{2}/u.test('\uD83D\uDE80\uD83D\uDE80') 
true 


> /\uD83D\uDE80{2}/.test('\uD83D\uDE80\uD83D\uDE80') 
false 

> /\uD83D\uDE80{2}/.test('\uD83D\uDE80\uDE80') 

true 


23.4 New data property flags 


In ECMAScript 6, regular expressions have the following data properties: 


e The pattern: source 

e The flags: flags 

e Individual flags: global, ignoreCase, multiline, sticky, unicode 
e Other: lastIndex 


As an aside, LastIndex is the only instance property now, all other data properties are implemented 
via internal instance properties and getters such as get RegExp.prototype.global?. 


The property source (which already existed in ES5) contains the regular expression pattern as a 
string: 


> /abc/ig.source 
‘abc' 


The property flags is new, it contains the flags as a string, with one character per flag: 


*http://www.ecma-international.org/ecma-262/6.0/#sec-get-regexp.prototype.global 


New regular expression features 430 


> /abc/ig.flags 
‘gi! 


You can’t change the flags of an existing regular expression (ignoreCase etc. have always been 
immutable), but flags allows you to make a copy where the flags are changed: 


function copyWithIgnoreCase(regex) { 


return new RegExp(regex.source, regex. flags+'i'); 


The next section explains another way to make modified copies of regular expressions. 


23.5 RegExp() can be used as a copy constructor 


In ES6 there are two variants of the constructor RegExp() (the second one is new): 


e new RegExp(pattern : string, flags = '') 
A new regular expression is created as specified via pattern. If flags is missing, the empty 
string '' is used. 

e new RegExp(regex : RegExp, flags = regex.flags) 
regex is cloned. If flags is provided then it determines the flags of the copy. 


The following interaction demonstrates the latter variant: 
> new RegExp(/abc/ig).flags 
! gi ! 


> new RegExp(/abc/ig, 'i').flags // change flags 
Va! 


Therefore, the RegExp constructor gives us another way to change flags: 


function copyWithIgnoreCase(regex) { 
return new RegExp(regex, regex.flags+'1'); 
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23.6 String methods using regular expressions 
delegate to regular expression methods 


The following string methods now delegate their work to regular expression methods: 


e String.prototype.match calls RegExp.prototype[Symbol.match]. 

e String.prototype.replace calls RegExp.prototype[Symbol.replace]. 
e String.prototype.search calls RegExp.prototype[Symbol. search]. 

e String.prototype.split calls RegExp .prototype[Symbol.split]. 


EA Further reading 


If you want to know in more detail how the regular expression flag /u works, I recommend 
the article “Unicode-aware regular expressions in ECMAScript 6%” by Mathias Bynens. 


*https://mathiasbynens.be/notes/es6-unicode-regex 
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24. Asynchronous programming 
(background) 


This chapter explains foundations of asynchronous programming in JavaScript. It provides back- 
ground knowledge for the next chapter on ES6 Promises. 


24.1 The JavaScript call stack 


When a function f calls a function g, g needs to know where to return to (inside f) after it is done. 
This information is usually managed with a stack, the call stack. Let's look at an example. 


function h(z) { 
// Print stack trace 
console. log(new Error().stack); // (A) 
} 
function g(y) { 
h(y + 1); // (B) 
} 
function f(x) { 
g(x + 1); // (0) 
} 
f(3); // (D) 
return; // (E) 


Initially, when the program above is started, the call stack is empty. After the function call f (3) in 
line D, the stack has one entry: 


e Location in global scope 
After the function call g(x + 1) in line C, the stack has two entries: 


e Location in f 
e Location in global scope 


After the function call h(y + 1) in line B, the stack has three entries: 
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e Location in g 
e Location in f 
e Location in global scope 


The stack trace printed in line A shows you what the call stack looks like: 


Error 
at h (stack_trace.js:2:17) 
at g (stack_trace.js:6:5) 
at f (stack_trace.js:9:5) 
at <global> (stack_trace.js:11:1) 


Next, each of the functions terminates and each time the top entry is removed from the stack. After 
function f is done, we are back in global scope and the call stack is empty. In line E we return and 
the stack is empty, which means that the program terminates. 


24.2 The browser event loop 


Simplifyingly, each browser tab runs (in) a single process: the event loop’. This loop executes 
browser-related things (so-called tasks) that it is fed via a task queue. Examples of tasks are: 


1. Parsing HTML 

2. Executing JavaScript code in script elements 

3. Reacting to user input (mouse clicks, key presses, etc.) 

4. Processing the result of an asynchronous network request 


Items 2-4 are tasks that run JavaScript code, via the engine built into the browser. They terminate 
when the code terminates. Then the next task from the queue can be executed. The following 
diagram (inspired by a slide by Philip Roberts [1]) gives an overview of how all these mechanisms 
are connected. 


*https://html.spec.whatwg.org/multipage/webappapis.html#event-loop 
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JavaScript engine Task sources: 


* DOM manipulation 
Call stack e User interaction 

* Networking 
History traversal 


Currently running task 


onTimeout 


Event loop O 


MC [oro [ 


Task queue 


The event loop is surrounded by other processes running in parallel to it (timers, input handling, 
etc.). These processes communicate with it by adding tasks to its queue. 


24.2.1 Timers 


Browsers have timers’. setTimeout() creates a timer, waits until it fires and then adds a task to 
the queue. It has the signature: 


setTimeout (callback, ms) 


After ms milliseconds, callback is added to the task queue. It is important to note that ms only 
specifies when the callback is added, not when it actually executed. That may happen much later, 
especially if the event loop is blocked (as demonstrated later in this chapter). 


setTimeout () with ms set to zero is a commonly used work-around to add something to the task 
queue right away. However, some browsers do not allow ms to be below a minimum (4 ms in Firefox); 
they set it to that minimum if it is. 


*https://html.spec.whatwg.org/multipage/webappapis.html#timers 
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24.2.2 Displaying DOM changes 


For most DOM changes (especially those involving a re-layout), the display isn't updated right away. 
“Layout happens off a refresh tick every 16ms” (@bz_moz’) and must be given a chance to run via 
the event loop. 


There are ways to coordinate frequent DOM updates with the browser, to avoid clashing with its 
layout rhythm. Consult the documentation? on requestAnimationFrame() for details. 


24.2.3 Run-to-completion semantics 


JavaScript has so-called run-to-completion semantics: The current task is always finished before the 
next task is executed. That means that each task has complete control over all current state and 
doesn't have to worry about concurrent modification. 


Let's look at an example: 


setTimeout(function () { // (A) 
console.log('Second'); 

+, 0); 

console.log('First'); // (B) 


The function starting in line A is added to the task queue immediately, but only executed after the 


current piece of code is done (in particular line B!). That means that this code’s output will always 
be: 


First 
Second 


24.2.4 Blocking the event loop 


As we have seen, each tab (in some browers, the complete browser) is managed by a single process — 
both the user interface and all other computations. That means that you can freeze the user interface 
by performing a long-running computation in that process. The following code demonstrates that. 


$https://twitter.com/bz_moz/status/513777809287028736 
‘https://developer.mozilla.org/en/docs/Web/API/window.requestAnimationFrame 
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<a id="block" href="">Block for 5 seconds</a> 
<p> 
<button>This is a button</button> 
<div id="statusMessage"></div> 
<script> 
document. getELementById('block') 
.addEventListener('click', onClick); 


function onClick(event) { 
event.preventDefauLt() ; 


setStatusMessage('Blocking...'); 


// Give browser the opportunity to display status message 
setTimeout (function () { 
blockMainThread(5000) ; 
setStatusMessage('Done'); 
+, 0); 
} 
function setStatusMessage(msg) { 
document.getElementById('statusMessage').textContent = msg; 
} 
function blockMainThread(milliseconds) { 
var start = Date.now(); 
while ((Date.now() - start) < milliseconds); 
} 


</script> 


lap) You can try out the code online’. 


Whenever the link at the beginning is clicked, the function onClick() is triggered. It uses the — 
synchronous — sleep () function to block the event loop for five seconds. During those seconds, the 
user interface doesn’t work. For example, you can’t click the “Simple button”. 


24.2.5 Avoiding blocking 


You avoid blocking the event loop in two ways: 


First, you don’t perform long-running computations in the main process, you move them to a 
different process. This can be achieved via the Worker API°. 


*http://rauschma.github.io/async-examples/blocking html 
*https://developer.mozilla.org/en/docs/Web/API/Worker 
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Second, you don't (synchronously) wait for the results of a long-running computation (your own 
algorithm in a Worker process, a network request, etc.), you carry on with the event loop and let the 
computation notify you when it is finished. In fact, you usually don't even have a choice in browsers 
and have to do things this way. For example, there is no built-in way to sleep synchronously (like 
the previously implemented sleep ()). Instead, setTimeout () lets you sleep asynchronously. 


The next section explains techniques for waiting asynchronously for results. 


24.3 Receiving results asynchronously 


Two common patterns for receiving results asynchronously are: events and callbacks. 


24.3.1 Asynchronous results via events 


In this pattern for asynchronously receiving results, you create an object for each request and 
register event handlers with it: one for a successful computation, another one for handling errors. 
The following code shows how that works with the XMLHttpRequest API: 


var req = new XMLHttpRequest(); 
req.open('GET', url); 


req.onload = function () { 
if (req.status == 200) { 
processData(req.response) ; 
} else { 
console. log('ERROR', req.statusText) ; 


}; 


req.onerror = function () { 
console.log('Network Error'); 


F; 
req.send(); // Add request to task queue 


Note that the last line doesn't actually perform the request, it adds it to the task queue. Therefore, 
you could also call that method right after open(), before setting up onload and onerror. Things 
would work the same, due to JavaScript’s run-to-completion semantics. 


24.3.1.1 Implicit requests 


The browser API IndexedDB has a slightly peculiar style of event handling: 
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var openRequest = indexedDB.open('test', 1); 


openRequest.onsuccess = function (event) ( 
console.log('Success!'); 
var db = event.target.result; 


}; 


openRequest.onerror = function (error) { 
console. log(error) ; 


$5 


You first create a request object, to which you add event listeners that are notified of results. 
However, you don’t need to explicitly queue the request, that is done by open(). It is executed 
after the current task is finished. That is why you can (and in fact must) register event handlers 
after calling open(). 


If you are used to multi-threaded programming languages, this style of handling requests probably 
looks strange, as if it may be prone to race conditions. But, due to run to completion, things are 
always safe. 


24.3.1.2 Events don’t work well for single results 


This style of handling asynchronously computed results is OK if you receive results multiple times. 
If, however, there is only a single result then the verbosity becomes a problem. For that use case, 
callbacks have become popular. 


24.3.2 Asynchronous results via callbacks 


If you handle asynchronous results via callbacks, you pass callback functions as trailing parameters 
to asynchronous function or method calls. 


The following is an example in Node.js. We read the contents of a text file via an asynchronous call 
to fs.readFile(): 


// Node.js 
fs.readFile('myfile.txt', { encoding: 'utf8' }, 
function (error, text) { // (A) 
if (error) { 
fI sxa 
} 
console. log(text) 5 


}); 
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If readFile() is successful, the callback in line A receives a result via the parameter text. If it isn’t, 
the callback gets an error (often an instance of Error or a sub-constructor) via its first parameter. 


The same code in classic functional programming style would look like this: 


// Functional 
readFileFunctional('myfile.txt', { encoding: 'utf8' }, 
function (text) { // success 
console. log(text) 5 
3, 
function (error) { // failure 
Al a 
}); 


24.3.3 Continuation-passing style 


The programming style of using callbacks (especially in the functional manner shown previously) 
is also called continuation-passing style (CPS), because the next step (the continuation) is explicitly 
passed as a parameter. This gives an invoked function more control over what happens next and 
when. 


The following code illustrates CPS: 


console. log('A'); 
identity('B', function step2(result2) { 
console.log(result2); 
identity('C', function step3(result3) { 
console.log(result3); 
H; 
console. log('D'); 
$; 


console. log('E'); 
// Output: AE BDC 


function identity(input, callback) { 
setTimeout(function () { 
callback(input) ; 
+, 0); 


For each step, the control flow of the program continues inside the callback. This leads to 
nested functions, which are sometimes referred to as callback hell. However, you can often avoid 
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nesting, because JavaScript’s function declarations are hoisted (their definitions are evaluated at the 
beginning of their scope). That means that you can call ahead and invoke functions defined later in 
the program. The following code uses hoisting to flatten the previous example. 


console. log('A'); 
identity('B', step2); 
function step2(result2) ( 
// The program continues here 
console.log(result2); 
identity('C', step3); 
console. log('D'); 
} 
function step3(result3) { 
console.log(result3); 
} 


console. log('E'); 


More information on CPS is given in [3]. 


24.3.4 Composing code in CPS 


In normal JavaScript style, you compose pieces of code via: 


1. Putting them one after another. This is blindingly obvious, but it’s good to remind ourselves 
that concatenating code in normal style is sequential composition. 

2. Array methods such as map(), filter() and forEach() 

3. Loops such as for and while 


The library Async.js’ provides combinators to let you do similar things in CPS, with Node.js-style 
callbacks. It is used in the following example to load the contents of three files, whose names are 
stored in an Array. 


"https://github.com/caolan/async 
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var async = require('async'); 


var fileNames = [ 'foo.txt', 'bar.txt', 'baz.txt' ]; 
async.map(fileNames, 
function (fileName, callback) { 
fs.readFile(fileName, { encoding: 'utf8' }, callback); 
}s 
// Process the result 
function (error, textArray) { 
if (error) { 
console. log(error); 
return; 
} 
console.log('TEXTS:1n' + textArray.join('\n----\n')); 
}); 


24.3.5 Pros and cons of callbacks 
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Using callbacks results in a radically different programming style, CPS. The main advantage of CPS 


is that its basic mechanisms are easy to understand. But there are also disadvantages: 


e Error handling becomes more complicated: There are now two ways in which errors are 
reported — via callbacks and via exceptions. You have to be careful to combine both properly. 
e Less elegant signatures: In synchronous functions, there is a clear separation of concerns 
between input (parameters) and output (function result). In asynchronous functions that use 
callbacks, these concerns are mixed: the function result doesn't matter and some parameters 


are used for input, others for output. 


e Composition is more complicated: Because the concern “output” shows up in the parameters, 


it is more complicated to compose code via combinators. 


Callbacks in Node.js style have three disadvantages (compared to those in a functional style): 


e The if statement for error handling adds verbosity. 
e Reusing error handlers is harder. 


e Providing a default error handler is also harder. A default error handler is useful if you make 
a function call and don’t want to write your own handler. It could also be used by a function 


if a caller doesn’t specify a handler. 


24.4 Looking ahead 


The next chapter covers Promises and the ES6 Promise API. Promises are more complicated under 
the hood than callbacks. In exchange, they bring several significant advantages and eliminate most 


of the aforementioned cons of callbacks. 
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24.5 Further reading 


[1] “Help, I’m stuck in an event-loop*” by Philip Roberts (video). 
[2] “Event loops?” in the HTML Specification. 


[3] “Asynchronous programming and continuation-passing style in JavaScript'” by Axel Rauschmayer. 


Shttp://vimeo.com/96425312 
*https://html.spec.whatwg.org/multipage/webappapis.html#event-loops 
MP http://www.2ality.com/2012/06/continuation-passing-style.html 


25. Promises for asynchronous 
programming 


This chapter is an introduction to asynchronous programming via Promises in general and the 
ECMAScript 6 Promise API in particular. The previous chapter explains the foundations of 
asynchronous programming in JavaScript. You can consult it whenever there is something that you 
don't understand in this chapter. 


25.1 Overview 
The following function returns a result asynchronously, via a Promise: 


function asyncFunc() { 
return new Promise( 
function (resolve, reject) { 
resolve(value); // success 


reject(error); // failure 


+); 


You call asyncFunc() as follows: 


asyncFunc() 
.then (value => { /* success */ }) 
.catch(error => { /* failure */ JP); 


25.1.1 Handling Arrays of Promises 


Promise.all() lets you react to an Array of Promises. 


For example, you can create an Array of Promises via the Array method map(): 
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let fileUrls = [ 
'http://example.com/filel.txt', 
'http://example.com/file2.txt' 

1; 

let promisedTexts = fileUrls.map(httpGet); // Array of Promises 


If you apply Promise.all() to that Array, you receive an Array of values once all Promises are 
fulfilled: 


Promise.all(promisedTexts) 
// Success 
.then (texts => { 
for (let text of texts) { 
console. log(text) 5 


+) 
// Failure 
.catch(reason => { 
// Receives first rejection among 'promisedTexts' 


H; 


25.2 Promises 


Promises are a pattern that helps with one particular kind of asynchronous programming: a function 
(or method) that returns its result asynchronously. To implement such a function, you return a 
Promise, an object that is a placeholder for the result. The caller of the function registers callbacks 
with the Promise to be notified once the result has been computed. The function sends the result via 
the Promise. 


The de-facto standard for JavaScript Promises is called Promises/A+ [1]. The ECMAScript 6 Promise 
API follows that standard. 


25.3 A first example 


Let's look at a first example, to give you a taste of what working with Promises is like. 


With Node.js-style callbacks, reading a file asynchronously looks like this: 
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fs.readFile('config.json', 
function (error, text) { 
if (error) { 
console.error('Error while reading config file'); 
} else { 
try { 
let obj = JSON.parse(text) ; 
console. lLog(JSON.stringify(obj, null, 4)); 
} catch (e) { 
console.error('Invalid JSON in file'); 


y); 
With Promises, the same functionality is implemented like this: 


readFilePromisified('config.json') 
.then (function (text) { // (A) 
let obj = JSON.parse(text) ; 
console. log(JSON.stringify(obj, null, 4)); 


}) 

.catch(function (reason) { // (B) 
// File read error or JSON SyntaxError 
console.error('An error occurred', reason); 


$»; 
There are still callbacks, but they are provided via methods that are invoked on the result (then () 
and catch()). The error callback in line B is convenient in two ways: First, it's a single style of 


handling errors (versus if (error) and try-catch in the previous example). Second, you can 
handle the errors ofboth readFilePromisified() and the callback in line A from a single location. 


The code of readFilePromisified() is shown later. 
25.4 Creating and using Promises 
Let’s look at how Promises are operated from the producer and the consumer side. 


25.4.1 Producing a Promise 


As a producer, you create a Promise and send a result via it: 
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let promise = new Promise( 
function (resolve, reject) { // (A) 


if (Ce) { 
resolve(value); // success 
} else { 


reject(reason); // failure 


}); 


A Promise is always in either one of three (mutually exclusive) states: 


e Pending: the result hasn't been computed, yet 
e Fulfilled: the result was computed successfully 
e Rejected: a failure occurred during computation 
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A Promise is settled (the computation it represents has finished) if it is either fulfilled or rejected. 
A Promise can only be settled once and then stays settled. Subsequent attempts to settle it have no 


effect. 


The parameter of new Promise() (starting in line A) is called an executor: 


ea. ooo. 


e Ifthe computation went well, the executor sends the result via resolve (). That usually fulfills 


the Promise (it may not, if you resolve with a Promise, as explained later). 


e Ifan error happened, the executor notifies the Promise consumer via reject (). That always 


rejects the Promise. 


25.4.2 Consuming a Promise 


As a consumer of promise, you are notified of a fulfillment or a rejection via reactions — callbacks 


that you register with the method then(): 
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promise.then( 
function (value) { /* fulfillment x/ }, 
function (reason) { /* rejection */ } 


); 


What makes Promises so useful for asynchronous functions (with one-off results) is that once a 
Promise is settled, it doesn’t change anymore. Furthermore, there are never any race conditions, 
because it doesn’t matter whether you invoke then () before or after a Promise is settled: 


e Reactions that are registered with a Promise before it is settled, are notified of the settlement 
once it happens. 

e Reactions that are registered with a Promise after it is settled, receive the cached settled value 
“immediately” (their invocations are queued as tasks). 


25.4.3 Only handling fulfillments or rejections 


If you are only interested in fulfillments, you can omit the second parameter of then(): 


promise.then( 
function (value) { /* fulfillment x*/ } 
)5 


If you are only interested in rejections, you can omit the first parameter. The method catch() isa 
more compact way of doing the same thing. 


promise. then( 
null, 
function (reason) { /* rejection */ } 


); 


// Equivalent: 
promise.catch( 
function (reason) { /* rejection */ } 


); 


It is recommended to use then() exclusively for fulfillments and catch() for errors, because it 
nicely labels callbacks and because you can handle the rejections of multiple Promises at the same 
time (details are explained later). 
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25.5 Examples 


Before we dig deeper into Promises, let's use what we have learned so far in a few examples. 


lap) Some of the examples in this section are available in the GitHub repository 
promise-examples?. 


25.5.1 Example: promisifying fs.readFile() 
The following code is a Promise-based version of the built-in Node.js function fs. readFile()?. 


import {readFile} from 'fs'; 


function readFilePromisified(filename) { 
return new Promise( 
function (resolve, reject) { 
readFile(filename, { encoding: 'utf8' }, 
(error, data) => { 
if (error) { 
reject(error) ; 
} 
resolve(data) ; 
H; 
H; 
} 


readFilePromisified() is used like this: 


readFilePromisified(process.argv[2]) 
.then (text => { 
console. log(text); 
}) 
.catch(error => { 
console.log(error); 


}); 
25.5.2 Example: promisifying XMLHttpRequest 


The following is a Promise-based function that performs an HTTP GET via the event-based 
XMLHttpRequest? API: 


*https://github.com/rauschma/promise-examples 
*https:/ /nodejs.org/api/fs.html#fs_fs_readfile_filename_options_callback 
Shttps://xhr.spec.whatwg.org/ 
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function httpGet(url) { 
return new Promise( 
function (resolve, reject) { 
let request = new XMLHttpRequest () ; 
request.onreadystatechange = function () { 
if (this.status === 200) { 
// Success 
resolve(this. response) ; 
} else { 
// Something went wrong (404 etc.) 
reject(new Error(this.statusText)); 


} 
request.onerror = function () { 
reject(new Error( 
'XMLHttpRequest Error: '+this.statusText)); 
}; 
request.open('GET', url); 
request.send(); 


}); 


This is how you use httpGet(): 


httpGet('http://example.com/file.txt') 


. then( 
function (value) { 
console. log('Contents: ' + value); 
3, 


function (reason) { 
console.error('Something went wrong', reason); 
}); 
25.5.3 Example: delaying an activity 


Let's implement setTimeout () as the Promise-based function delay () (similar to Q.delay()%). 


“https://github.com/kriskowal/q/wiki/API-Reference#qdelayms 
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function delay(ms) { 
return new Promise(function (resolve, reject) { 
setTimeout(resolve, ms); // (A) 


+33 


// Using delay(): 
delay(5000).then(function () { // (B) 
console.log('5 seconds have passed!') 


H; 


Note that in line A, we are calling resolve with zero parameters, which is the same as calling 
resolve (undefined). We don't need the fulfillment value in line B, either and simply ignore it. 
Just being notified is enough here. 


25.5.4 Example: timing out a Promise 


function timeout(ms, promise) { 
return new Promise(function (resolve, reject) { 
promise.then(resolve); 
setTimeout(function () { 
reject(new Error('Timeout after '+ms+' ms')); // (A) 
}, ms); 
H; 
} 


Note that the rejection after the timeout (in line A) does not cancel the request, but it does prevent 
the Promise being fulfilled with its result. 


Using timeout () looks like this: 


timeout(5000, httpGet('http://example.com/file.txt')) 
.then (function (value) { 
console.log('Contents: ' + value); 


}) 
.catch(function (reason) { 
console.error('Error or timeout', reason); 


H); 
25.6 Chaining Promises 


Now we are ready to dig deeper into the features of Promises. Let's first explore how you can chain 
Promises. 


The result of the method call: 
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P.then(onFulfilled, onRejected) 


is a new Promise Q. That means that you can keep the Promise-based control flow going by invoking 
then() on Q: 


e Q is resolved with what is returned by either onFulfilled or onRejected. 
e Q is rejected if either onFulfilled or onRejected throw an exception. 


25.6.1 Resolving Q with normal values 


If you resolve the Promise Q returned by then() with a normal value, you can pick up that value 
via a subsequent then (): 


asyncFunc() 

.then (function (valuel) { 
return 123; 

}) 

.then (function (value2) { 
console.log(value2); // 123 


}); 

25.6.2 Resolving Q with thenables 

You can also resolve the Promise Q returned by then () with a thenable R. A thenable is any object 
that has a Promise-style method then(). Thus, Promises are thenable. Resolving with R (e.g. by 


returning it from onFulfilled) means that it is inserted “after” Q: R’s settlement is forwarded to 
Q’s onFulfilled and onRejected callbacks. In a way, Q becomes R. 


insert here 
P.then(function () { return R }) -then(onFulfilled, onRejected) 


Q 


The main use for this mechanism is to flatten nested then() calls, like in the following example: 
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asyncFuncl() 

.then (function (valuel) { 
asyncFunc2() 
.then(function (value2) { 


}); 
}) 


The flat version looks like this: 


asyncFunc1() 
.then (function (valuel) { 
return asyncFunc2(); 


}) 
.then (function (value2) { 


}) 


25.6.3 Resolving Q from onRejected 


Whatever you return in an error handler becomes a fulfillment value (not rejection value!). That 
allows you to specify default values that are used in case of failure: 


retrieveFileName() 

.catch(function () { 
// Something went wrong, use a default value 
return 'Untitled.txt'; 


$) 

.then(function (fileName) { 

}); 

25.6.4 Rejecting Q by throwing exceptions 


Exceptions that are thrown in either one of then’s parameters are passed on to the next error 
handler: 
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asyncFunc() 

.then (function (value) { 
throw new Error(); 

}) 

.catch(function (reason) { 
// Handle error here 


}); 
25.6.5 Exceptions in executors 


An exception thrown inside an executor (the callback of new Promise()) is passed to the error 
handler of the Promise managed by that executor: 


new Promise(function (resolve, reject) { 
throw new Error(); 

}) 

.catch(function (err) { 
// Handle error here 


}); 
25.6.6 Chaining errors 


There can be one or more then() method calls that don’t have an error handler. Then the error is 
passed on until there is an error handler. 


asyncFunc1() 
. then (asyncFunc2) 
. then (asyncFunc3) 
.catch(function (reason) { 
// Something went wrong above 


}); 
25.7 Composition 


This section describes how you can compose existing Promises to create new ones. We have already 
encountered one way of composing Promises: sequential chaining via then (). Promise.all() and 
Promise.race() provide additional ways of composing. 


25.7.1 map ( ) via Promise.all() 


One nice thing about Promises is that many synchronous tools still work, because Promise-based 
functions return results. For example, you can use the Array method map (): 
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let fileUrls = [ 
'http://example.com/filel.txt', 
'http://example.com/file2.txt' 

1; 

let promisedTexts = fileUrls.map(httpGet) ; 


promisedTexts is an Array of Promises. Promise.all() takes an Array of Promises (thenables 
and other values are converted to Promises via Promise.resolve()) and, once all of them are 
fulfilled, it fulfills with an Array of their values: 


Promise.all(promisedTexts) 
.then (texts => { 
for (let text of texts) { 
console. log(text) 5 


+) 
.catch(reason => { 
// Receives first rejection among the Promises 


H; 


25.7.2 Timing out via Promise.race() 


Promise. race() takes an Array of Promises (thenables and other values are converted to Promises 
via Promise.resolve()) and returns a Promise P. The first of the input Promises that is settled 
passes its settlement on to the output Promise. 


As an example, let's use Promise.race() to implement a timeout: 


Promise.race([ 
httpGet('http://example.com/file.txt'), 
delay(5000).then(function () { 

throw new Error('Timed out') 


H; 
]) 
.then (function (text) { °°: }) 
.catch(function (reason) { +++ })3 


25.8 Promises are always async 


A Promise library has complete control over whether results are delivered to Promise reactions 
synchronously (right away) or asynchronously (after the current continuation, the current piece of 
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code, is finished). However, the Promises/A+ specification demands that the latter mode of execution 
be always used. It states so via the following requirement? (2.2.4) for the then () method: 


onFulfilled or onRejected must not be called until the execution context stack 
contains only platform code. 


That means that you code can rely on run-to-completion semantics (as explained in part 1) and that 
chaining Promises won't starve other tasks of processing time. 


25.9 Cheat sheet: the ECMAScript 6 Promise API 


This section gives an overview of the ECMAScript 6 Promise API, as described in the specification’. 


25.9.1 Glossary: Promises 


The Promise API is about delivering results asynchronously. A Promise object (short: Promise) is a 
stand-in for the result, which is delivered via that object. 


States: 


e A Promise is always in either one of three mutually exclusive states: 

— Before the result is ready, the Promise is pending. 

— If a result is available, the Promise is fulfilled. 

— If an error happened, the Promise is rejected. 
e A Promise is settled if “things are done” (if it is either fulfilled or rejected). 
e A Promise is settled exactly once and then remains unchanged. 


Reacting to state changes: 


e Promise reactions are callbacks that you register with the Promise method then(), to be 
notified of a fulfillment or a rejection. 

e A thenable is an object that has a Promise-style then() method. Whenever the API is only 
interested in being notified of settlements, it only demands thenables. 


Changing states: There are two operations for changing the state of a Promise. After you have 
invoked either one of them once, further invocations have no effect. 


e Rejecting a Promise means that the Promise becomes rejected. 
e Resolving a Promise has different effects, depending on what value you are resolving with: 
— Resolving with a normal (non-thenable) value fulfills the Promise. 
— Resolving a Promise P with a thenable T means that P can’t be resolved anymore and 
will now follow T’s state, including its fulfillment or rejection value. The appropriate P 
reactions will get called once T settles (or are called immediately if T is already settled). 


*http://promisesaplus.com/#point-34 


*http://www.ecma-international.org/ecma-262/6.0/#sec-promise-objects 
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25.9.2 Promise constructor 


The constructor for Promises is invoked as follows: 
let p = new Promise(function (resolve, reject) { =: }); 


The callback of this constructor is called an executor. The executor can use its parameters to resolve 
or reject the new Promise p: 


e resolve(x) resolves p with x: 
— If x is thenable, its settlement is forwarded to p (which includes triggering reactions 
registered via then()). 
— Otherwise, p is fulfilled with x. 
e reject(e) rejects p with the value e (often an instance of Error’). 


25.9.3 Static Promise methods 


All static methods of Promise support subclassing: 


e They create new Promise instances via the so-called species pattern (which is explained in 
detail in the chapter on classes): 
— The default is to use the receiver (this) as the constructor. 
— That default can be overridden via the property [Symbol.species] in subclasses. 
e Other static methods are also accessed via the species pattern (not via Promise or via this). 


25.9.3.1 Creating Promises 


The following two static methods create new instances of their receivers: 


e Promise. resolve(x): converts arbitrary values to Promises, with an awareness of thenables 
and Promises. 
- If x is thenable, it is converted to a Promise — an instance of the receiver (this; the 
species pattern is not used here). 
— If x is already an instance of the receiver, it is returned unchanged. 
— Otherwise, return a new instance of the receiver that is fulfilled with x. 
e Promise. reject(reason): creates a new instance of the receiver (as configured via the 
species pattern) that is rejected with the value reason. 


"http://speakingjs.com/es5/ch14.html#error_constructors 
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25.9.3.2 Composing Promises 


Intuitively, the static methods Promise.all() and Promise. race() compose iterables of Promises 
to a single Promise. That is: 


e They take an iterable. The elements of the iterable are converted to Promises via this . resolve ()®. 


e They return a new Promise. That Promise is a new instance of the receiver (as configured via 
the species pattern). 


The methods are: 


e Promise.all(iterable): returns a Promise that... 
— is fulfilled if all elements in iterable are fulfilled. 
Fulfillment value: Array with fulfillment values. 
— is rejected if any of the elements are rejected. 
Rejection value: first rejection value. 
e Promise. race(iterable): the first element of iterable that is settled is used to settle the 
returned Promise. 


25.9.4 Promise.prototype methods 


25.9.4.1 Promise.prototype.then(onFulfilled, onRejected) 


e The callbacks onFulfilled and onRejected are called reactions. 
e onFulfilled is called immediately if the Promise is already fulfilled or as soon as it becomes 
fulfilled. Similarly, onRej ected is informed of rejections. 
e then() returns a new Promise Q (created via the the species of the constructor of the receiver): 
— If either of the reactions returns a value, Q is resolved with it. 
— If either of the reactions throws an exception, Q is rejected with it. 
e Omitted reactions: 
— If onFulfilled has been omitted, a fulfillment of the receiver is forwarded to the result 
of then(). 
— If onRejected has been omitted, a rejection of the receiver is forwarded to the result of 
then(). 


Default values for omitted reactions could be implemented like this: 


SThis is a slight simplification. Actually, the elements are converted via C. resolve (), where C is determined via the species pattern. 
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function defaultOnFulfilled(x) { 


return x; 

} 

function defaultOnRejected(e) { 
throw e; 

} 


25.9.4.2 Promise.prototype.catch(onRejected) 


e p.catch(onRejected) is the same as p.then(null, onRejected). 


25.10 Pros and cons of Promises 


25.10.1 The pros 


25.10.1.1 Unifying asynchronous APIs 


One important advantage of Promises is that they will increasingly be used by asynchronous browser 
APIs and unify currently diverse and incompatible patterns and conventions. Let’s look at two 
upcoming Promise-based APIs. 


The fetch API is a Promise-based alternative to XMLHttpRequest: 


fetch(url) 
.then(request => request.text()) 
.then(str => »»-) 


fetch() returns a Promise for the actual request, text () returns a Promise for the content as a 
string. 
The ECMAScript 6 API for programmatically importing modules is based on Promises, too: 


System. import ('some_module.js') 
.then(some_module => { 


+) 


25.10.1.2 Promises versus events 


Compared to events, Promises are better for handling one-off results. It doesn't matter whether you 
register for a result before or after it has been computed, you will get it. This advantage of Promises is 
fundamental in nature. On the flip side, you can't use them for handling recurring events. Chaining 
is another advantage of Promises, but one that could be added to event handling. 
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25.10.1.3 Promises versus callbacks 


Compared to callbacks, Promises have cleaner function (or method) signatures. With callbacks, 
parameters are used for input and output: 


fs.readFile(name, opts?, (err, string | Buffer) => void) 
With Promises, all parameters are used for input: 
readFilePromisified(name, opts?) : Promise<string | Buffer> 


Additional Promise advantages include better error handling (which integrates exceptions) and eas- 
ier composition (because you can reuse some synchronous tools such as Array.prototype.map()). 


25.10.2 The cons 
Promises work well for for single asynchronous results. They are not suited for: 
e Recurring events: If you are interested in those, take a look at reactive programming’, which 
add a clever way of chaining to normal event handling. 
e Streams of data: A standard*” for supporting those is currently in development. 
ECMAScript 6 Promises lack two features that are sometimes useful: 
e You can’t cancel them. 
e You can't query them for how far along they are (e.g. to display a progress bar in a client-side 


user interface). 


The Q Promise library has support'* for the latter and there are plans” to add both capabilities to 
Promises/A+. 


25.11 Promises and generators 


In the following code, I use the control flow library co** to asynchronously retrieve two JSON files. 
Note how, in line A, execution blocks (waits) until the result of Promise. all() is ready. That means 
that the code looks synchronous while performing asynchronous operations. 


"http://reactive-extensions.github.io/Rx]S/ 
“https://streams.spec.whatwg.org/ 
“https://github.com/kriskowal/q+progress- notification 
“https://github.com/promises-aplus 
https://github.com/tj/co 
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co(functionx () { 
try { 

let [croftStr, bondStr] = yield Promise.all([ // (A) 
getFile('http://localhost:8000/croft.json'), 
getFile('http://localhost:8000/bond.json'), 

1); 

let croftJson = JSON.parse(croftStr) ; 

let bondJson = JSON.parse(bondStr) ; 


console. log(croftJson) ; 
console. log(bondJson) ; 


} catch (e) { 
console.log('Failure to read: ' + e); 


H); 


Details are explained in the chapter on generators. 


25.12 Debugging Promises 


Tools for debugging Promises are slowly appearing in browsers. Let's take a quick look at what the 
latest version of Google Chrome has to offer. The following is part of an HTML file that demonstrates 
two common problems with Promises: 


<body> 
<script> 
// Unhandled rejection 
Promise.reject(new Error()) 
.then (function (x) { return 'a'}) 
.then (function (x) { return 'b'}) 
// Unsettled Promise 
new Promise(function () {}); 
</script> 
</body> 


First, a rejection isn’t handled. Second, a Promise isn’t settled. Chrome’s dev tools help with both 
problems. 


Unhandled rejections are logged in the console: 
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Q Elements Network Sources Timeline Profiles |\Console| » ©1 >. $ O, x 


O Y <topframe> vw [Preserve log 


© PUncaught (in promise) Error(..) debugging promises.html:10 
> 


r 1 


They are also highlighted in the “Sources” inspector: 


Q Elements Network | Sources | Timeline Profiles Resources Audits » 091 >_ % oO, x 


>] | debugging_promises.html x | El 
7| <body> 
8 <script> 
9 // Unhandled rejection 
10 Promise. reject(new Error()) @ 
11 .«then(function (x return a'*) 
E «then(function (x) 4 jii © Uncaught (in promise) Error 
14 // Unsettled Promise 
15 new Promise(function () {}); 
16 </script> 


17. </hodu> 
{} Line 10, Column 24 


r 


Lastly, there is a special inspector for Promises that logs all Promises that are created by a web page. 
Among other things, it records: 


e Which Promises are fulfilled (green bullet in first column), rejected (red bullet) and pending 
(gray bullet) 
e How Promises are chained 


Console Search Emulation Rendering | Promises 


© © Y F Dasync 


Function Created Settled Time to settle 
0 Y (anonymous function) debugging promises.html:10 debugging promises.html:10 Oms 
@ Y (anonymous function) debugging promises.html:11 lms 
@ (anonymous function) debugging promises.html:12 lms 


(anonymous function) debugging promises.html:15 
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25.13 The internals of Promises 


In this section, we will approach Promises from a different angle: Instead of learning how to use 
the API, we will look at a simple implementation of it. This different angle helped me greatly with 
making sense of Promises. 


The Promise implementation is called DemoPromise. In order to be easier to understand, it doesn't 
completely match the API. But it is close enough to still give you much insight into the challenges 
that actual implementations are facing. 


lap) DemoPromi se is available on GitHub, in the repository demo_promise™. 


DemoPromise is a class with three prototype methods: 


e DemoPromise.prototype.resolve(value) 
e DemoPromise.prototype.reject(reason) 
. DemoPromise.prototype.then(onFulfilled, onRejected) 


That is, resolve and reject are methods (versus functions handed to a callback parameter of the 
constructor). 


25.13.1 A stand-alone Promise 


Our first implementation is a stand-alone Promise with minimal functionality: 


e You can create a Promise. 
e You can resolve or reject a Promise and you can only do it once. 
e You can register reactions (callbacks) via then (). It must work independently of whether the 
Promise has already been settled or not. 
— This method does not support chaining, yet — it does not return anything. 


This is how this first implementation is used: 


“https://github.com/rauschma/demo_promise 
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let dp = new DemoPromise(); 

dp.resolve('abc'); 

dp.then(function (value) { 
console.log(value); // abc 


p; 


The following diagram illustrates how our first DemoPromise works: 


resolve(x1) 
f onFulfilled(x1) 


reject(e1) | 
onRejected(e1) 


25.13.1.1 DemoPromise. prototype. then() 


Let’s examine then() first. It has to handle two cases: 


e If the Promise is still pending, it queues invocations of onFulfilled and onRejected, to be 
used when the Promise is settled. 

e If the Promise is already fulfilled or rejected, onFulfilled or onRejected can be invoked 
right away. 


then(onFulfilled, onRejected) { 
let self = this; 
let fulfilledTask = function () { 
onFulfilled(self.promiseResult); 
$5 
let rejectedTask = function () { 
onRejected(self.promiseResult) ; 
$5 
switch (this.promiseState) { 
case 'pending': 
this. fulfillReactions.push(fulfilledTask) ; 
this.rejectReactions.push(rejectedTask) ; 
break; 
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case 'fulfilled': 
addToTaskQueue(fulfilledTask) ; 
break; 

case 'rejected': 
addToTaskQueue(rejectedTask) ; 
break; 


The previous code snippet uses the following helper function: 


function addToTaskQueue(task) { 
setTimeout(task, 0); 


25.13.1.2 DemoPromise. prototype. resolve() 


resolve() works as follows: If the Promise is already settled, it does nothing (ensuring that a 
Promise can only be settled once). Otherwise, the state of the Promise changes to 'fulfilled' 
and the result is cached in this.promiseResult. Next, all fulfillment reactions, that have been 
enqueued so far, are be triggered. 


resolve(value) { 
if (this.promiseState !== 'pending') return; 
this.promiseState = 'fulfilled'; 
this.promiseResult = value; 
this._clearAndEnqueueReactions (this. fulfillReactions) ; 
return this; // enable chaining 

} 

_clearAndEnqueueReactions(reactions) { 
this.fulfillReactions = undefined; 
this.rejectReactions = undefined; 
reactions.map(addToTaskQueue) ; 


reject() is similar to resolve(). 


25.13.2 Chaining 


The next feature we implement is chaining: 
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e then() returns a Promise that is resolved with what either onFulfilled or onRejected 
return. 

e If onFulfilled or onRejected are missing, whatever they would have received is passed 
on to the Promise returned by then(). 


returns 


resolve(x1) resolve(x2) 


onFulfilled(x1) 


reject(e1) reject(e2) 


onRejected(e1) 


Obviously, only then() changes: 


then(onFulfilled, onRejected) { 
let returnValue = new Promise(); // (A) 
let self = this; 


let fulfilledTask; 
if (typeof onFulfilled === 'function') { 
fulfilledTask = function () { 
let r = onFulfilled(self.promiseResult) 5 
returnValue.resolve(r); // (B) 
}; 
} else { 
fulfilledTask = function () { 
returnValue.resolve(self.promiseResult); // (C) 


}; 


let rejectedTask; 
if (typeof onRejected === 'function') { 
rejectedTask = function () { 
let r = onRejected(self.promiseResult); 
returnValue.resolve(r); // (D) 


}; 
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} else { 
rejectedTask = function () ( 
// “onRejected” has not been provided 
// => we must pass on the rejection 
returnValue.reject(self.promiseResult); // (E) 


}; 
return returnValue; // (F) 


then() creates and returns a new Promise (lines A and F). Additionally, fulfilledTask and 
rejectedTask are set up differently: After a settlement... 


+ The result of onFulfilled is used to resolve returnValue (line B). 
— If onFulfilled is missing, we use the fulfillment value to resolve returnValue (line 
©). 
+ The result of onRejected is used to resolve (not reject!) returnValue (line D). 
- If onRejected is missing, we use pass on the rejection value to returnValue (line E). 


25.13.3 Flattening 


Flattening is mostly about making chaining more convenient: Normally, returning a value from a 
reaction passes it on to the next then(). If we return a Promise, it would be nice if it could be 
“unwrapped” for us, like in the following example: 


asyncFuncl() 
.then(function (valuel) { 
return asyncFunc2(); // (A) 


}) 

.then (function (value2) { 
// value2 is fulfillment value of asyncFunc2() Promise 
console. log(value2); 


H; 


We returned a Promise in line A and didn't have to nest a call to then () inside the current method, 
we could invoke then() on the method’s result. Thus: no nested then (), everything remains flat. 


We implement this by letting the resolve () method do the flattening: 


e Resolving a Promise P with a Promise Q means that Q’s settlement is forwarded to P’s 
reactions. 
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e P becomes “locked in” on Q: it can't be resolved (incl. rejected), anymore. And its state and 
result are always the same as Q’s. 


We can make flattening more generic if we allow Q to be a thenable (instead of only a Promise). 


returns 
x1 : NonThenable 


| resolve(x2) 


reject(e2) 


' x1: Thenable : 
A 


To implement locking-in, we introduce a new boolean flag this. alreadyResolved. Once it is true, 
this is locked and can't be resolved anymore. Note that this may still be pending, because its state 
is now the same as the Promise it is locked in on. 


resolve(value) { 
if (this.alreadyResolved) return; 
this.alreadyResolved = true; 
this._doResolve(value) ; 
return this; // enable chaining 


The actual resolution now happens in the private method _doResolve(): 


_doResolve(value) { 

let self = this; 
// Is ‘value’ a thenable? 
if (typeof value === 'object' && value !== null && 'then' in value) ( 

// Forward fulfillments and rejections from ‘value’ to ‘this’. 

// Added as a task (vs. done immediately) to preserve async semantics. 

addToTaskQueue(function () { // (A) 

value. then( 
function onFulfilled(result) ( 
self._doResolve(result) ; 
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Fy 
function onRejected(error) { 
self._doReject(error); 
$; 
$; 
j else { 
this.promiseState = 'fulfilled'; 
this.promiseResult = value; 
this._clearAndEnqueueReactions (this. fulfillReactions) ; 


The flattening is performed in line A: If value is fulfilled, we want self to be fulfilled and if 
value is rejected, we want self to be rejected. The forwarding happens via the private methods 
_doResolve and _doReject, to get around the protection via alreadyResolved. 


25.13.4 Promise states in more detail 


With chaining, the states of Promises become more complex (as covered by Sect. 25.4"° of the 
ECMAScript 6 specification): 


E | 
resolve with 1 
non-promise 


Pending 


Ejec; 
resolve with 
promise Q 


Locked-in on Q 


If you are only using Promises, you can normally adopt a simplified worldview and ignore locking- 
in. The most important state-related concept remains “settledness”: a Promise is settled if it is either 
fulfilled or rejected. After a Promise is settled, it doesn't change, anymore (state and fulfillment or 
rejection value). 


http://www.ecma-international.org/ecma-262/6.0/#sec-promise-objects 
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If you want to implement Promises then “resolving” matters, too and is now harder to understand: 


e Intuitively, “resolved” means “can't be (directly) resolved anymore”. A Promise is resolved if 
it is either settled or locked in. Quoting the spec: “An unresolved Promise is always in the 
pending state. A resolved Promise may be pending, fulfilled or rejected.” 

e Resolving does not necessarily lead to settling: you can resolve a Promise with another one 
that is always pending. 

e Resolving now includes rejecting (i.e., it is more general): you can reject a Promise by resolving 
it with a rejected Promise. 


25.13.5 Exceptions 


As our final feature, we'd like our Promises to handle exceptions in user code as rejections. For now, 
“user code” means the two callback parameters of then(). 


returns 


x1 : NonThenable 


resolve(x1) resolve(x2) 


reject(e1) reject(e2) 


; x1: Thenable : 
Arto 


The following excerpt shows how we turn exceptions inside onFulfilled into rejections — by 
wrapping a try-catch around its invocation in line A. 


then(onFulfilled, onRejected) { 


let fulfilledTask; 


if (typeof onFulfilled === 'function') { 
fulfilledTask = function () { 
try { 


let r = onFulfilled(self.promiseResult); // (A) 
returnValue.resolve(r); 

} catch (e) { 
returnValue. reject(e); 
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$; 
j else { 
fulfilledTask = function () { 
returnValue.resolve(self.promiseResult); 


}; 


25.13.6 Revealing constructor pattern 
If we wanted to turn DemoPromise into an actual Promise implementation, we'd still need to 


implement the revealing constructor pattern [5]: ES6 Promises are not resolved and rejected via 
methods, but via functions that are handed to the executor, the callback parameter of the constructor. 


returns 


ix) resolve(x2) 


onFulfilled(x1) 


reject(e1) reject(e2) 


If the executor throws an exception then “its” Promise must be rejected. 


25.14 Two useful additional Promise methods 


This section describes two useful methods that are easy to add to ES6 Promises. Many of the more 
comprehensive Promise libraries have them. 


25.14.1 done () 


When you chain several Promise method calls, you risk silently discarding errors. For example: 
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function doSomething() { 
asyncFunc() 
. then(f1) 
.catch(r1) 
.then(f2); // (A) 


If then() in line A produces a rejection, it will never be handled anywhere. The Promise library 
Q provides a method done(), to be used as the last element in a chain of method calls. It either 
replaces the last then() (and has one to two arguments): 


function doSomething() { 
asyncFunc() 
.then(f1) 
.catch(r1) 
.done(f2) ; 


Or it is inserted after the last then() (and has zero arguments): 


function doSomething() { 
asyncFunc() 
.then(f1) 
.catch(r1) 
.then(f2) 
.done(); 


Quoting the Q documentation”: 


The Golden Rule of done vs. then usage is: either return your promise to someone else, 
or if the chain ends with you, call done to terminate it. Terminating with catch is not 
sufficient because the catch handler may itself throw an error. 


This is how you would implement done() in ECMAScript 6: 


**https://github.com/kriskowal/q/wiki/API-Reference#promisedoneonfulfilled-onrejected-onprogress 
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Promise.prototype.done = function (onFulfilled, onRejected) { 
this.then(onFulfilled, onRejected) 
.catch(function (reason) { 
// Throw an exception globally 
setTimeout(() => { throw reason }, 0); 
$; 
+3 


While done’s functionality is clearly useful, it has not been added to ECMAScript 6, because this kind 
of check can be performed automatically by engines (as we have seen in the section on debugging 
Promises). 


25.14.2 finally () 


Sometimes you want to perform an action independently of whether an error happened or not. For 
example, to clean up after you are done with a resource. That’s what the Promise method finally () 
is for, which works much like the finally clause in exception handling. Its callback receives no 
arguments, but is notified of either a resolution or a rejection. 


createResource(:::) 

.then (function (valuel) { 
// Use resource 

}) 

.then (function (value2) { 
// Use resource 

}) 

.finally (function () { 
// Clean up 

$; 


This is how Domenic Denicola proposes” to implement finally (): 


https://github.com/domenic/promises-unwrapping/issues/18 
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Promise.prototype. finally = function (callback) ( 


let P = this.constructor; 

// We don’t invoke the callback in here, 

// because we want then() to handle its exceptions 

return this. then( 
// Callback fulfills => continue with receiver’s fulfillment or rejection 
// Callback rejects => pass on that rejection (then() has no 2nd paramet\ 


er!) 


$5 


value => P.resolve(callback()).then(() => value), 
reason => P.resolve(callback()).then(() => { throw reason }) 


)3 


The callback determines how the settlement of the receiver (this) is handled: 


e If the callback throws an exception or returns a rejected Promise then that becomes/con- 
tributes the rejection value. 
e Otherwise, the settlement (fulfillment or rejection) of the receiver becomes the settlement 


of the Promise returned by finally(). In a way, we take finally() out of the chain of 
methods. 


Example 1 (by Jake Archibald**): using finally () to hide a spinner. Simplified version: 


showSpinner () ; 

fetchGalleryData() 

.then(data => updateGallery (data) ) 
.catch(showNoDataError) 

. finally (hideSpinner) ; 


Example 2 (by Kris Kowal”): using finally () to tear down a test. 


*$https://gist.github.com/jakearchibald/785f79b0dea5bfe0c448 
*https://github.com/domenic/promises-unwrapping/issues/18#issuecomment- 27707922 
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let HTTP = require("q-io/http") ; 
let server = HTTP.Server (app); 
return server.listen(0) 
.then(function () { 

// run test 
}) 


.finally(server.stop); 


25.15 ES6-compatible Promise libraries 


There are many Promise libraries out there. The following ones conform to the ECMAScript 6 API, 
which means that you can use them now and easily migrate to native ES6 later. 


e “RSVP.js”” by Stefan Penner is a superset of the ES6 Promise API. 
— “ES6-Promises”*” by Jake Archibald extracts just the ES6 API out of RSVP.js. 

e “Native Promise Only (NPO)”” by Kyle Simpson is “a polyfill for native ES6 promises, as close 
as possible (no extensions) to the strict spec definitions”. 

e “Lie?” by Calvin Metcalf is “a small, performant, promise library implementing the Promis- 
es/A+ spec”. 

e Q.Promise” by Kris Kowal implements the ES6 API. 

e Lastly, the “ES6 Shim?” by Paul Millr includes Promise. 


25.16 Interfacing with legacy asynchronous code 


When you are using a Promise library, you sometimes need to use non-Promise-based asynchronous 
code. This section explains how to do that for Node.js-style asynchronous functions and jQuery 
deferreds. 


25.16.1 Interfacing with Node.js 


The Promise library Q has several tool functions”? for converting functions that use Node.js-style 
(err, result) callbacks to ones that return a Promise (there are even functions that do the opposite 
— convert Promise-based functions to ones that accept callbacks). For example: 


20), 
21), 
22), 
23), 
24, 
25), 
26), 


ps://github.com/tildeio/rsvp.js/ 
ps://github.com/jakearchibald/es6- promise 
ps://github.com/getify/native-promise- only 
ps://github.com/calvinmetcalf/lie 
ps://github.com/kriskowal/q#using-qpromise 
ps://github.com/paulmillr/es6-shim 
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ps://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks 
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let readFile = Q.denodeify(FS.readFile) ; 


readFile('foo.txt', 'utf-8') 
.then(function (text) ( 


H; 


denodify” is a micro-library that only provides the “denodification” functionality and complies with 
the ECMAScript 6 Promise API. 


25.16.2 Interfacing with jQuery 


jQuery has deferreds”* which are similar to Promises, but have several differences”? that prevent 
compatibility. Their method then() is almost like that of ES6 Promises (main difference: it 
doesn't catch errors in reactions). Thus, we can convert a ¡Query deferred to an ES6 Promise via 
Promise.resolve(): 


Promise.resolve( 


jQuery .ajax(1 
url: 'somefile.html', 
type: 'GET' 

})) 


.then(function (data) { 
console. log(data) ; 
}) 
.catch(function (reason) { 
console.error (reason) ; 
}); 
?7https://github.com/matthew-andrews/denodeify/ 
*8http://api.jquery.com/category/deferred-object/ 


https://github.com/kriskowal/q/wiki/Coming-from-¡Query 
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25.17 Further reading 


[1] *Promises/A+*”, edited by Brian Cavalier and Domenic Denicola (the de-facto standard for 
JavaScript Promises) 


[2] “JavaScript Promises: There and back again?” by Jake Archibald (good general intro to Promises) 
[3] “Promise Anti-Patterns*”” by Tao of Code (tips and techniques) 
[4] “Promise Patterns?” by Forbes Lindesay 


[5] “The Revealing Constructor Pattern**” by Domenic Denicola (this pattern is used by the Promise 
constructor) 


*°http://promisesaplus.com/ 
**http://www.html5rocks.com/en/tutorials/es6/promises/ 
**http://taoofcode.net/promise-anti-patterns/ 
*Shttps://www.promisejs.org/patterns/ 
*4http://domenic.me/2014/02/13/the-revealing-constructor-pattern/ 


VI Miscellaneous 


26. Unicode in ES6 


This chapter explains the improved support for Unicode that ECMAScript 6 brings. For a general 
introduction to Unicode, read “Unicode and JavaScript?” (a chapter in “Speaking JavaScript”). 


26.1 Unicode is better supported in ES6 


There are three areas in which ECMAScript 6 has improved support for Unicode: 


e Unicode escapes for code points beyond 16 bits: Yuf : + +} 
Can be used in identifiers, string literals, template literals and regular expression literals. They 
are explained in the next section. 
e Strings: 
— Iteration honors Unicode code points. 
— Read code point values via String.prototype.codePointAt(). 
— Create a string from code point values via String. fromCodePoint(). 
e Regular expressions: 
— New flag /u (plus boolean property unicode) improves handling of surrogate pairs. 


26.2 Escape sequences in ES6 


There are three parameterized escape sequences for representing characters in JavaScript: 


e Hex escape (exactly two hexadecimal digits): \xHH 


e Unicode escape (exactly four hexadecimal digits): YuHHHH 


> '\uQO7A' === 'z' 
true 


e Unicode code point escape (1 or more hexadecimal digits): \u{* + +} 


*http://speakingjs.com/es5/ch24.html 
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> '\uf{7A}! === 'z' 
true 


Unicode code point escapes are new in ES6. They let you specify code points beyond 16 bits. If you 
wanted to do that in ECMAScript 5, you had to encode each code point as two UTF-16 code units (a 
surrogate pair). These code units could be expressed via Unicode escapes. For example, the following 
statement logs a rocket (code point 0x1F680) to most consoles: 


console. log('\uD83D\uDE80') ; 
With a Unicode code point escape you can specify code points greater than 16 bits directly: 


console. log('\u{1F680}'); 


26.2.1 Where can escape sequences be used? 


The escape sequences can be used in the following locations: 


\uHHHH \u{*°*} \xHH 
Identifiers J J 
String literals Y Y J 
Template literals J Y J 
Regular expression literals V Only with flag /u Z 


Identifiers: 


e A 4-digit Unicode escape YuHHHH becomes a single code point. 
e A Unicode code point escape Yuf * ++} becomes a single code point. 


> let hello = 123; 
> hell\u{6F} 
123 


String literals: 
e Strings are internally stored as UTF-16 code units. 


e A hex escape \xHH contributes a UTF-16 code unit. 
e A 4-digit Unicode escape YuHHHH contributes a UTF-16 code unit. 
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e A Unicode code point escape Yuf : > +} contributes the UTF-16 encoding of its code point (one 
or two UTF-16 code units). 


Template literals: 


e In template literals, escape sequences are handled like in string literals. 
e In tagged templates, how escape sequences are interpreted depends on the tag function. It can 
choose between two interpretations: 
— Cooked: escape sequences are handled like in string literals. 
— Raw: escape sequences are handled as a sequence of characters. 


> “hell\uf{6F}* // cooked 
"hello! 

> String.raw hell\u{6F}° // raw 
"hell\\uf{6F}! 


Regular expressions: 


e Unicode code point escapes are only allowed if the flag /u is set, because \u{3} is interpreted 
as three times the character u, otherwise: 


> /\uf{3}$/.test('uuu') 
true 


26.2.2 Escape sequences in the ES6 spec 


Various information: 


e The spec treats source code as a sequence of Unicode code points: “Source Text” 

e Unicode escape sequences sequences in identifiers: “Names and Keywords?” 

Strings are internally stored as sequences of UTF-16 code units: “String Literals*” 

e Strings — how various escape sequences are translated to UTF-16 code units: “Static Semantics: 
sv” 


e Template literals - how various escape sequences are translated to UTF-16 code units: “Static 
Semantics: TV and TRV*” 


*http://www.ecma-international.org/ecma-262/6.0/#sec-source-text 
*http://www.ecma-international.org/ecma-262/6.0/#sec-names-and-keywords 
“http://www.ecma-international.org/ecma-262/6.0/#sec-literals-string-literals 
*http://www.ecma-international.org/ecma-262/6.0/#sec-static- semantics- sv 
*http://www.ecma-international.org/ecma-262/6.0/#sec-static-semantics-tv-and-trv 
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26.2.2.1 Regular expressions 


The spec distinguishes between BMP patterns (flag /u not set) and Unicode patterns (flag /u set). 
Sect. “Pattern Semantics”” explains that they are handled differently and how. 


As a reminder, here is how grammar rules are be parameterized in the spec: 


e Ifa grammar rule R has the subscript [U] then that means there are two versions of it: R and 
R_U. 

e Parts of the rule can pass on the subscript via [?U]. 

e Ifa part of a rule has the prefix [+U] it only exists if the subscript [U] is present. 

e Ifa part of a rule has the prefix [~U] it only exists if the subscript [U] is not present. 


You can see this parameterization in action in Sect. “Patterns*”, where the subscript [U] creates 
separate grammars for BMP patterns and Unicode patterns: 


e IdentityEscape: In BMP patterns, many characters can be prefixed with a backslash and are 
interpreted as themselves (for example: if \u is not followed by four hexadecimal digits, it 
is interpreted as u). In Unicode patterns that only works for the following characters (which 
frees up Yu for Unicode code point escapes): ° $ Y . * +? () [147] 

e RegExpUnicodeEscapeSequence: "\u{" HexDigits "}" is only allowed in Unicode patterns. 
In those patterns, lead and trail surrogates are also grouped to help with UTF-16 decoding. 


Sect. “CharacterEscape”” explains how various escape sequences are translated to characters 
(roughly: either code units or code points). 


EN Further reading 


“JavaScript has a Unicode problem 
in ES6. 


1” (by Mathias Bynens) explains new Unicode features 


"http://www.ecma-international.org/ecma-262/6.0/#sec-pattern-semantics 
Shttp://www.ecma-international.org/ecma-262/6.0/*sec-patterns 
"http://www.ecma-international.org/ecma-262/6.0/*sec-characterescape 
“https://mathiasbynens.be/notes/javascript-unicode 


27. Tail call optimization 


ECMAScript 6 offers tail call optimization, where you can make some function calls without growing 
the call stack. This chapter explains how that works and what benefits it brings. 


27.1 What is tail call optimization? 


To understand what tail call optimization (TCO) is, we will examine the following piece of code. I'll 
first explain how it is executed without TCO and then with TCO. 


function id(x) { 
return x; // (A) 


} 

function f(a) { 
let b = a + 1; 
return id(b); // (B) 


} 
console. log(f(2))3 // (©) 


27.1.1 Normal execution 


Let’s assume there is a JavaScript engine that manages function calls by storing local variables and 
return addresses on a stack. How would such an engine execute the code? 


Step 1. Initially, there are only the global variables id and f on the stack. 


f = function (a) {= } Global stack frame 
) 


id = function (x) { 


The block of stack entries encodes the state (local variables, including parameters) of the current 
scope and is called a stack frame. 


Step 2. In line C, f() is called: First, the location to return to is saved on the stack. Then f’s 
parameters are allocated and execution jumps to its body. The stack now looks as follows. 
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Stack frame of f() 


) 


id = function (x) { --- } 


There are now two frames on the stack: One for the global scope (bottom) and one for f () (top). f’s 
stack frame includes the return address, line C. 


Step 3. id() is called in line B. Again, a stack frame is created that contains the return address and 
id’s parameter. 


Stack frame of id() 


Stack frame of f() 


Global stack frame 


f = function (a) {= } 
) 


id = function (x) { 


Step 4. In line A, the result x is returned. id’s stack frame is removed and execution jumps to the 
return address, line B. (There are several ways in which returning a value could be handled. Two 
common solutions are to leave the result on a stack or to hand it over in a register. I ignore this part 
of execution here.) 


The stack now looks as follows: 
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Stack frame of f() 


f = function (a) {= } Global stack frame 
id = function (x) {= } 


Step 5. In line B, the value that was returned by id is returned to f’s caller. Again, the topmost stack 
frame is removed and execution jumps to the return address, line C. 


f = function (a) { = } Global stack frame 
) 


id = function (x) { 


Step 6. Line C receives the value 3 and logs it. 


27.1.2 Tail call optimization 


function id(x) { 
return x; // (A) 
} 
function f(a) { 
let b = a + 1; 
return id(b); // (B) 
} 
console. log(f(2)); // (C) 


If you look at the previous section then there is one step that is unnecessary — step 5. All that happens 
in line B is that the value returned by id() is passed on to line C. Ideally, id() could do that itself 
and the intermediate step could be skipped. 


We can make this happen by implementing the function call in line B differently. Before the call 
happens, the stack looks as follows. 
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Stack frame of f() 


) 


id = function (x) {= } 


If we examine the call we see that it is the very last action in f(). Once id() is done, the only 
remaining action performed by f() is to pass id’s result to f’s caller. Therefore, f”s variables are 
not needed, anymore and its stack frame can be removed before making the call. The return address 
given to id() is f’s return address, line C. During the execution of id(), the stack looks like this: 


Stack frame of id() 


Global stack frame 


f = function (a) {= } 
) 


id = function (x) { 


Then id() returns the value 3. You could say that it returns that value for f (), because it transports 
it to f’s caller, line C. 


Let’s review: The function call in line B is a tail call. Such a call can be done with zero stack growth. 
To find out whether a function call is a tail call, we must check whether it is in a tail position (i.e., 
the last action in a function). How that is done is explained in the next section. 


27.2 Checking whether a function call is in a tail 
position 


We have just learned that tail calls are function calls that can be executed more efficiently. But what 
counts as a tail call? 


First, the way in which you call a function does not matter. The following calls can all be optimized 
if they appear in a tail position: 


¢ Function call: func (+-+) 

e Dispatched method call: obj .method(: ++) 

¢ Direct method call via call(): func.call(: ++) 

+ Direct method call via apply (): func.apply (+-+) 
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27.2.1 Tail calls in expressions 


Arrow functions can have expressions as bodies. For tail call optimization, we therefore have to 
figure out where function calls are in tail positions in expressions. Only the following expressions 
can contain tail calls: 


e The conditional operator (? :) 
e The logical Or operator (| |) 

+ The logical And operator (&&) 
e The comma operator (,) 


Let's look at an example for each one of them. 


27.2.1.1 The conditional operator (? :) 


const a = x => x? f() : gO; 
Both f() and g() are in tail position. 


27.2.1.2 The logical Or operator (| |) 


const a = () => f() || g0; 


f() is not in a tail position, but g() is in a tail position. To see why, take a look at the following 
code, which is equivalent to the previous code: 


const a = () => { 
let fResult = 
if (fResult) { 
return fResult; 
} else { 
return g(); // tail call 


f(); // not a tail call 


} 
}; 


The result of the logical Or operator depends on the result of f (), which is why that function call 
is not in a tail position (the caller does something with it other than returning it). However, g () is 
in a tail position. 


27.2.1.3 The logical And operator 
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const a = () => f() & g(); 


f() is not in a tail position, but g() is in a tail position. To see why, take a look at the following 
code, which is equivalent to the previous code: 


const a = () => { 
let fResult = f(); // not a tail call 
if (!fResult) ( 
return fResult; 
} else Y 
return g(); // tail call 
} 
$; 


The result of the logical And operator depends on the result of f (), which is why that function call 
is not in a tail position (the caller does something with it other than returning it). However, g() is 
in a tail position. 


27.2.1.4 The comma operator (,) 


const a = () => (f() , 80); 


f() is not in a tail position, but g() is in a tail position. To see why, take a look at the following 
code, which is equivalent to the previous code: 


const a = () => { 
FO; 


return g(); 


27.2.2 Tail calls in statements 


For statements, the following rules apply. 


Only these compound statements can contain tail calls: 


e Blocks (as delimited by {}, with or without a label) 
e if: in either the “then” clause or the “else” clause. 

e do-whi le, while, for: in their bodies. 

e switch: in its body. 


Tail call optimization 488 


e try-catch: only in the catch clause. The try clause has the catch clause as a context that 
can’t be optimized away. 


e try-finally, try-catch-finally: only in the finally clause, which is a context of the 
other clauses that can’t be optimized away. 


Of all the atomic (non-compound) statements, only return can contain a tail call. All other 
statements have context that can’t be optimized away. The following statement contains a tail call 
if expr contains a tail call. 


return «expr»; 


27.2.3 Tail call optimization can only be made in strict mode 


In non-strict mode, most engines have the following two properties that allow you to examine the 
call stack: 


e func.arguments: contains the arguments of the most recent invocation of func. 
e func.caller: refers to the function that most recently called func. 


With tail call optimization, these properties don’t work, because the information that they rely on 
may have been removed. Therefore, strict mode forbids these properties (as described in the language 
specification’) and tail call optimization only works in strict mode. 


27.2.4 Pitfall: solo function calls are never in tail position 


The function call bar () in the following code is not in tail position: 


function foo() { 
bar(); // this is not a tail call in JS 


The reason is that the last action of foo() is not the function call bar (), it is (implicitly) returning 
undefined. In other words, foo() behaves like this: 


*http://www.ecma-international.org/ecma-262/6.0/#sec-addrestrictedfunctionproperties 
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function foo() { 
bar(); 
return undefined; 


} 


Callers can rely on foo () always returning undefined. If bar () were to return a result for foo (), 
due to tail call optimization, then that would change foo’s behavior. 


Therefore, if we want bar () to be a tail call, we have to change foo() as follows. 


function foo() { 
return bar(); // tail call 


27.3 Tail-recursive functions 


A function is tail-recursive if the main recursive calls it makes are in tail positions. 


For example, the following function is not tail recursive, because the main recursive call in line A is 
not in a tail position: 


function factorial(x) { 
if (x <= 0) { 
return 1; 
} else { 
return x x factorial(x-1); // (A) 


} 


factorial() can be implemented via a tail-recursive helper function facRec(). The main 
recursive call in line A is in a tail position. 


function factorial(n) { 
return facRec(n, 1); 


} 
function facRec(x, acc) { 
if (x <= 1) { 
return acc; 
} else { 
return facRec(x-1, xxacc); // (A) 


} 


That is, some non-tail-recursive functions can be transformed into tail-recursive functions. 
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27.3.1 Tail-recursive loops 


Tail call optimization makes it possible to implement loops via recursion without growing the stack. 
The following are two examples. 


27.3.1.1 forEach() 


function forEach(arr, callback, start = 0) ( 
if (0 <= start && start < arr.length) { 
callback(arr[start], start, arr); 
return forEach(arr, callback, start+1); // tail call 


} 
forEach(['a', 'b'], (elem, i) => console. log( $11). ${elem}`)); 


// Output: 
// 0. a 
E ee EA o 


27.3.1.2 findIndex() 


function findIndex(arr, predicate, start = 0) { 
if (0 <= start && start < arr.length) { 
if (predicate(arr[start])) { 
return start; 


} 


return findIndex(arr, predicate, start+1); // tail call 


} 
findIndex(['a', 'b'], x => x === 'b'); // 1 


28. Meta programming with proxies 


This chapter explains the ECMAScript 6 feature proxies. Proxies enable you to intercept and cus- 
tomize operations performed on objects (such as getting properties). They are a meta programming 
feature. 


28.1 Overview 


In the following example, proxy is the object object whose operations we are intercepting and 
handler is the object that handles the interceptions. In this case, we are only intercepting a single 
operation, get (getting properties). 


let target = {}; 
let handler = { 
get(target, propKey, receiver) { 
console. log('get ' + propKey); 
return 123; 


$5 
let proxy = new Proxy(target, handler); 


When we get the property proxy. foo, the handler intercepts that operation: 


> proxy. foo 
get foo 
123 


A section at the end of this chapter serves as a reference to the complete API and lists what operations 
can be intercepted. 


28.2 Programming versus meta programming 
Before we can get into what proxies are and why they are useful, we first need to understand what 
meta programming is. 


In programming, there are levels: 
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e At the base level (also called: application level), code processes user input. 
e At the meta level, code processes base level code. 


Base and meta level can be diffent languages. In the following meta program, the meta programming 
language is JavaScript and the base programming language is Java. 


let str = 'Hello' + '!'.repeat(3); 
console.log('System.out.println("'+str+'")'); 


Meta programming can take different forms. In the previous example, we have printed Java code 
to the console. Let's use JavaScript as both meta programming language and base programming 
language. The classic example for this is the eval() function’, which lets you evaluate/compile 
JavaScript code on the fly. There are not that many actual use cases’ for eval (). In the interaction 
below, we use it to evaluate the expression 5 + 2. 


> eval('5 + 2') 
7 


Other JavaScript operations may not look like meta programming, but actually are, ifyou look closer: 


// Base level 
let obj = { 
hello() { 
console. log('Hello!'); 


$5 


// Meta level 
for (let key of Object.keys(obj)) { 
console.log(key) ; 


The program is examining its own structure while running. This doesn't look like meta program- 
ming, because the separation between programming constructs and data structures is fuzzy in 
JavaScript. All of the Object.» methods? can be considered meta programming functionality. 


*http:/ /speakingjs.com/es5/ch23.html#_dynamically_evaluating_javascript_code_via_eval_and_new_function 
*http://speakingjs.com/es5/ch23.html#_legitimate_use_cases 
*http://speakingjs.com/es5/ch17.html#oop_cheat_sheet 
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28.2.1 Kinds of meta programming 


Reflective meta programming means that a program processes itself. Kiczales et al. [2] distinguish 
three kinds of reflective meta programming: 


e Introspection: you have read-only access to the structure of a program. 
e Self-modification: you can change that structure. 
e Intercession: you can redefine the semantics of some language operations. 


Let's look at examples. 
Example: introspection. Object .keys () performs introspection (see previous example). 


Example: self-modification. The following function moveProperty moves a property from a 
source to a target. It performs self-modification via the bracket operator for property access, the 
assignment operator and the delete operator. (In production code, you'd probably use property 
descriptors* for this task.) 


function moveProperty(source, propertyName, target) { 
target[propertyName] = source[propertyName] ; 
delete source[propertyName] ; 


Using moveProperty(): 


> let obj1 = { prop: 'abc' }; 
> let obj2 = {}; 
> moveProperty(obj1, 'prop', obj2); 


> objl 

{} 

> obj2 

{ prop: 'abc' } 


ECMAScript 5 doesn’t support intercession, proxies were created to fill that gap. 


“http://speakingjs.com/es5/ch17.html#property_attributes 
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28.3 A first look at proxies 


ECMAScript 6 proxies bring intercession to JavaScript. They work as follows. There are many 
operations that you can perform on an object obj. For example: 


e Getting the property prop of an object obj (obj . prop) 
e Checking whether an object obj has a property prop ('prop' in obj) 


Proxies are special objects that allow you customize some of these operations. A proxy is created 
with two parameters: 


e handler: For each operation, there is a corresponding handler method that — if present — 
performs that operation. Such a method intercepts the operation (on its way to the target) and 
is called a trap (a term borrowed from the domain of operating systems). 

e target: If the handler doesn’t intercept an operation then it is performed on the target. That 
is, it acts as a fallback for the handler. In a way, the proxy wraps the target. 


In the following example, the handler intercepts the operations get and has. 


let target = {}; 
let handler = { 
/xx Intercepts: getting properties x/ 
get(target, propKey, receiver) { 
console. log(* GET ${propKey}`); 
return 123; 


}, 


/xx Intercepts: checking whether properties exist x*x/ 
has(target, propKey) { 

console.log('HAS ${propKey}`); 

return true; 


35 
let proxy = new Proxy(target, handler); 


When we get property foo, the handler intercepts that operation: 
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> proxy.tfoo 
GET foo 
123 


Similarly, the in operator triggers has: 


> 'hello' in proxy 
HAS hello 
true 


The handler doesn’t implement the trap set (setting properties). Therefore, setting proxy .bar is 
forwarded to target and leads to target. bar being set. 


> proxy.bar = 'abc'; 
> target.bar 
‘abc! 


28.3.1 Function-specific traps 


If the target is a function, two additional operations can be intercepted: 


e apply: Making a function call, triggered via 
- proxy(+**) 
= proxy.call(:::) 
> proxy.apply(:+*+*) 
e construct: Making a constructor call, triggered via 
— new proxy(:::) 


The reason for only enabling these traps for function targets is simple: You wouldn’t be able to 
forward the operations apply and construct, otherwise. 


28.3.2 Revocable proxies 
ECMAScript 6 lets you create proxies that can be revoked (switched off): 
let {proxy, revoke} = Proxy.revocable(target, handler); 


On the left hand side of the assignment operator (=), we are using destructuring to access the 
properties proxy and revoke of the object returned by Proxy.revocable(). 


After you call the function revoke for the first time, any operation you apply to proxy causes a 
TypeError. Subsequent calls of revoke have no further effect. 
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let target = {}; // Start with an empty object 
let handler = {}; // Don’t intercept anything 
let (proxy, revoke} = Proxy.revocable(target, handler); 


proxy.foo = 123; 
console. log(proxy. foo); // 123 


revoke() ; 


console. log(proxy. foo); // TypeError: Revoked 


28.3.3 Proxies as prototypes 
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A proxy proto can become the prototype of an object obj. Some operations that begin in obj may 


continue in proto. One such operation is get. 


let proto = new Proxy({}, 4 
get(target, propertyKey, receiver) { 
console. log('GET '+propertyKey) ; 
return target[propertyKey]; 


p; 


let obj = Object.create(proto); 
obj.bla; 


// Output: 
// GET bla 


The property bla can't be found in obj, which is why the search continues in proto and the trap 
get is triggered there. There are more operations that affect prototypes, they are listed at the end of 


this chapter. 


28.3.4 Forwarding intercepted operations 


Operations whose traps the handler doesn't implement are automatically forwarded to the target. 
Sometimes there is some task you want to perform in addition to forwarding the operation. For 
example, a handler that intercepts all operations and logs them, but doesn't prevent them from 


reaching the target: 
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let handler = { 

deleteProperty(target, propKey) { 
console. log('DELETE ' + propKey) ; 
return delete target[propKey]; 

3, 

has(target, propKey) { 
console.log('HAS ' + propKey) ; 
return propKey in target; 

}s 

// Other traps: similar 


For each trap, we first log the name of the operation and then forward it by performing it manually. 
ECMAScript 6 has the module-like object Reflect that helps with forwarding: for each trap 


handler.trap(target, arg_1, ***, arg_n) 
Reflect has a method 

Reflect.trap(target, arg_1, ***, arg_n) 

If we use Ref lect, the previous example looks as follows. 


let handler = { 
deleteProperty(target, propKey) { 
console. log('DELETE ' + propKey) ; 
return Reflect.deleteProperty(target, propKey) ; 
}s 
has(target, propKey) { 
console.log('HAS ' + propKey); 
return Reflect.has(target, propKey) ; 


see 
// Other traps: similar 


Now what each of the traps does is so similar that we can implement the handler via a proxy: 
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let handler = new Proxy({}, 4 
get(target, trapName, receiver) { 

// Return the handler method named trapName 

return function (...args) { 
// Don’t log args[0] 
console. lLog(trapName. toUpperCase()+' '+args.slice(1)); 
// Forward the operation 
return Reflect[trapName](...args) ; 


}); 


For each trap, the proxy asks for a handler method via the get operation and we give it one. That 
is, all of the handler methods can be implemented via the single meta method get. It was one of the 
goals for the proxy API to make this kind of virtualization simple. 


Let's use this proxy-based handler: 


> let target = {}; 

> let proxy = new Proxy(target, handler); 
> proxy.foo = 123; 

SET fo0,123,[object Object] 

> proxy. foo 

GET foo, [object Object] 

123 


The following interaction confirms that the set operation was correctly forwarded to the target: 


> target.foo 
123 


28.4 Use cases for proxies 


This section demonstrates what proxies can be used for. That will also give you the opportunity to 
see the API in action. 


28.4.1 Implementing the DOM in JavaScript 


The browser Document Object Model (DOM) is usually implemented as a mix of JavaScript and 
C++. Implementing it in pure JavaScript is useful for: 
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e Emulating a browser environment, e.g. to manipulate HTML in Node.js. jsdom’ is one library 
that does that. 
e Speeding the DOM up (switching between JavaScript and C++ costs time). 


Alas, the standard DOM can do things that are not easy to replicate in JavaScript. For example, 
most DOM collections are live views on the current state of the DOM that change dynamically 
whenever the DOM changes. As a result, pure JavaScript implementations of the DOM are not very 
efficient. One of the reasons for adding proxies to JavaScript was to help write more efficient DOM 
implementations. 


28.4.2 Accessing a restful web service 


A proxy can be used to create an object on which arbitrary methods can be invoked. In the following 
example, the function createWebService creates one such object, service. Invoking a method on 
service retrieves the contents of the web service resource with the same name. Retrieval is handled 
via an ECMAScript 6 Promise. 


let service = createWebService('http://example.com/data'); 
// Read JSON data in http://example.com/data/employees 
service.employees().then(json => { 

let employees = JSON.parse(json) ; 


H; 


The following code is a quick and dirty implementation of createwebService in ECMAScript 
5. Because we don’t have proxies, we need to know beforehand what methods will be invoked 
on service. The parameter propKeys provides us with that information, it holds an Array with 
method names. 


function createWebService(baseUrl, propKeys) { 
let service = {}; 
propKeys.forEach(function (propKey) { 
Object.defineProperty(service, propKey, { 
get: function () { 
return httpGet(baseUrl+'/'+propKey); 


}); 
}); 
return service; 


} 


The ECMAScript 6 implementation of createWebService can use proxies and is simpler: 


*https://github.com/tmpvar/jsdom 
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function createWebService(baseUrl) ( 
return new Proxy({}, 4 
get(target, propKey, receiver) { 
return httpGet(baseUrl+'/'+propKey) ; 


}); 


Both implementations use the following function to make HTTP GET requests (how it works is 
explained in the chapter on Promises. 


function httpGet(url) { 
return new Promise( 
(resolve, reject) => { 
let request = new XMLHttpRequest(); 
Object.assign(request, { 
onreadystatechange() { 
if (this.status === 200) { 
// Success 
resolve(this.response); 
} else { 
// Something went wrong (404 etc.) 
reject(new Error(this.statusText)); 


Js 
onerror() { 
reject(new Error( 
'XMLHttpRequest Error: '+this.statusText)); 


}); 
request.open('GET', url); 
request.send(); 


H); 


28.4.3 Tracing property accesses 


The example in this section is inspired by Brendan Eich's talk “Proxies are Awesome”: We want to 
trace when a given set of properties is read or changed. To demonstrate how that works, let's create 
a class for points and trace accesses to the properties of an instance. 


*http://jsconf.eu/2010/speaker/be_proxy_objects.html 
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class Point { 
constructor(x, y) { 
this.x = x; 
this.y = y; 
} 
toString() { 
return 'Point('+this.x+','+this.y+')'; 


7 


// Trace accesses to properties 'x' and 'y' 
let p = new Point(5, 7); 
p = tracePropAccess(p, ['x', 'y']); 


Getting and setting properties of p now has the following effects: 


> p.x 
GET x 

5 

> p.x = 21 
SET x=21 
21 


Intriguingly, tracing also works whenever Point accesses the properties, because this now refers 
to the proxy, not to an instance of Point. 


> p.toString() 
GET x 

GET y 
'Point(21,7)' 


In ECMAScript 5, you'd implement tracePropAccess() as follows. We replace each property with 
a getter and a setter that traces accesses. The setters and getters use an extra object, propData, to 
store the data of the properties. Note that we are destructively changing the original implementation, 
which means that we are meta programming. 
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function tracePropAccess(obj, propKeys) { 
// Store the property data here 
let propData = Object.create(null) ; 
// Replace each property with a getter and a setter 
propKeys.forEach(function (propKey) { 
propData[propKey] = obj[propKey] ; 
Object.defineProperty(obj, propKey, + 
get: function () { 
console.log('GET '+propKey) ; 
return propData[propKey] ; 
}s 
set: function (value) { 
console.log('SET '+propKey+'='+value); 
propData[propKey] = value; 
}s 
}); 
}); 


return obj; 


In ECMAScript 6, we can use a simpler, proxy-based solution. We intercept property getting and 
setting and don’t have to change the implementation. 


function tracePropAccess(obj, propKeys) { 
let propKeySet = new Set(propKeys); 
return new Proxy(obj, { 
get(target, propKey, receiver) { 
if (propKeySet.has(propKey)) { 
console. log('GET '+propKey); 
} 
return Reflect.get(target, propKey, receiver); 
}s 
set(target, propKey, value, receiver) { 
if (propKeySet.has(propKey)) { 
console.log('SET '+propKey+'='+value); 
} 
return Reflect.set(target, propKey, value, receiver); 
3, 
$»; 
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28.4.4 Warning about unknown properties 


When it comes to accessing properties, JavaScript is very forgiving. For example, if you try to read a 
property and misspell its name, you don't get an exception, you get the result undefined. You can 
use proxies to get an exception in such a case. This works as follows. We make the proxy a prototype 
of an object. 


If a property isn't found in the object, the get trap of the proxy is triggered. If the property doesn't 
even exist in the prototype chain after the proxy, it really is missing and we throw an exception. 
Otherwise, we return the value of the inherited property. We do so by forwarding the get operation 
to the target (the prototype of the target is also the prototype of the proxy). 


let PropertyChecker = new Proxy({}, 4 
get(target, propKey, receiver) { 
if (!(propKey in target)) ( 
throw new ReferenceError('Unknown property: '+propKey) ; 


} 


return Reflect.get(target, propKey, receiver); 
}); 
Let's use PropertyChecker for an object that we create: 


> let obj = { __proto__: PropertyChecker, foo: 123 }; 
> obj.foo // own 

123 

> obj. fo 

ReferenceError: Unknown property: fo 

> obj.toString() // inherited 

'[object Object]' 


If we turn PropertyChecker into a constructor, we can use it for ECMAScript 6 classes via 
extends: 
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function PropertyChecker() { } 
PropertyChecker.prototype = new Proxy(:::); 


class Point extends PropertyChecker 4 
constructor(x, y) { 
this.x = x; 
this.y = y; 


let p = new Point(5, 7); 
console. log(p.x); // 5 
console. log(p.z); // ReferenceError 


If you are worried about accidentally creating properties, you have two options: You can either 
wrap a proxy around objects that traps set. Or you can make an object obj non-extensible via 
Object. preventExtensions (obj )’, which means that JavaScript doesn’t let you add new (own) 
properties to obj. 


28.4.5 Negative Array indices 


Some Array methods let you refer to the last element via -1, to the second-to-last element via -2, 
etc. For example: 


[rat,. "b", “e*].«slice(-1) 


Alas, that doesn’t work when accessing elements via the bracket operator ([]). We can, however, use 
proxies to add that capability. The following function createArray() creates Arrays that support 
negative indices. It does so by wrapping proxies around Array instances. The proxies intercept the 
get operation that is triggered by the bracket operator. 


"http://speakingjs.com/es5/ch17.html#_preventing_extensions 
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function createArray(...elements) ( 
let handler = { 

get(target, propKey, receiver) { 
let index = Number (propKey) ; 
// Sloppy way of checking for negative indices 
if (index < 0) { 

propKey = String(target.length + index); 

} 


return Reflect.get(target, propKey, receiver) ; 


$5 
// Wrap a proxy around an Array 
let target = []; 
target.push(...elements) ; 
return new Proxy(target, handler); 
} 
let arr = createArray('a', 'b', 'c'); 
console. log(arr[-1]); // c 


Acknowledgement: The idea for this example comes from a blog postë by hemanth.hm. 


28.4.6 Data binding 


Data binding is about syncing data between objects. One popular use case are widgets based on the 
MVC (Model View Controler) pattern: With data binding, the view (the widget) stays up-to-date if 
you change the model (the data visualized by the widget). 


To implement data binding, you have to observe and react to changes made to an object. In the 
following code snippet, I sketch how observing changes could work for an Array. 


let array = []; 
let observedArray = new Proxy(array, { 
set(target, propertyKey, value, receiver) { 
console.log(propertyKey+'='+value); 
Reflect.set((target, propertyKey, value, receiver); 


H; 


observedArray.push('a'); 


Output: 


*http://h3manth.com/new/blog/2013/negative-array-index-in-javascript/ 
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O=a 
length=1 


Data binding is a complex topic. Given its popularity and concerns over proxies not being performant 
enough, a dedicated mechanism has been created for data binding: Object .observe(). It will 
probably be part of ECMAScript 7 and is already supported” by Chrome. 


CG Consult Addy Osmani’s article “Data-binding Revolutions with Object.observe()'” for 
more information on Object.observe(). 


28.4.7 Revocable references 


Revocable references work as follows: A client is not allowed to access an important resource 
(an object) directly, only via a reference (an intermediate object, a wrapper around the resource). 
Normally, every operation applied to the reference is forwarded to the resource. After the client is 
done, the resource is protected by revoking the reference, by switching it off. Henceforth, applying 
operations to the reference throws exceptions and nothing is forwarded, anymore. 


In the following example, we create a revocable reference for a resource. We then read one of the 
resource’s properties via the reference. That works, because the reference grants us access. Next, we 
revoke the reference. Now the reference doesn’t let us read the property, anymore. 


let resource = { x: 11, y: 8 }; 
let {reference, revoke} = createRevocableReference(resource) ; 


// Access granted 
console. log(reference.x); // 11 


revoke() ; 


// Access denied 
console. lLog(reference.x); // TypeError: Revoked 


Proxies are ideally suited for implementing revocable references, because they can intercept and 
forward operations. This is a simple proxy-based implementation of createRevocableReference: 


*http://kangax.github.io/compat-table/es7/#Object.observe 
“http://www.html5rocks.com/en/tutorials/es7/observe/ 
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function createRevocableReference (target) { 
let enabled = true; 
return { 
reference: new Proxy(target, { 
get(target, propKey, receiver) { 
if (!enabled) { 
throw new TypeError('Revoked') ; 
i; 
return Reflect.get(target, propKey, receiver); 
> 
has (target, propKey) 4 
if (!lenabled) ( 
throw new TypeError('Revoked') ; 
F 
return Reflect.has(target, propKey); 


}, 


}), 
revoke() { 
enabled = false; 
}s 
}; 


The code can be simplified via the proxy-as-handler technique from the previous section. This time, 
the handler basically is the Reflect object. Thus, the get trap normally returns the appropriate 
Reflect method. If the reference has been revoked, a TypeError is thrown, instead 


function createRevocableReference(target) { 
let enabled = true; 
let handler = new Proxy({}, 4 
get(dummyTarget, trapName, receiver) { 
if (!enabled) { 
throw new TypeError('Revoked') ; 
} 


return Reflect[trapName]; 


}); 
return { 
reference: new Proxy(target, handler), 
revoke() { 
enabled = false; 
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}, 
}; 
} 


However, you don’t have to implement revocable references yourself, because ECMAScript 6 lets 
you create proxies that can be revoked. This time, the revoking happens in the proxy, not in the 
handler. All the handler has to do is forward every operation to the target. As we have seen that 
happens automatically if the handler doesn’t implement any traps. 


function createRevocableReference(target) { 
let handler = {}; // forward everything 
let { proxy, revoke } = Proxy.revocable(target, handler) ; 
return { reference: proxy, revoke }; 


} 
28.4.7.1 Membranes 


Membranes build on the idea of revocable references: Environments that are designed to run 
untrusted code, wrap a membrane around that code to isolate it and keep the rest of the system 
safe. Objects pass the membrane in two directions: 


e The code may receive objects from the outside. 
e Or it may hand objects to the outside. 


In both cases, revocable references are wrapped around the objects. Objects returned by wrapped 
functions or methods are also wrapped. 


Once the untrusted code is done, all of those references are revoked. As a result, none of its code 
on the outside can be executed anymore and outside objects that it has cease to work, as well. The 
Caja Compiler" is “a tool for making third party HTML, CSS and JavaScript safe to embed in your 
website”. It uses membranes to achieve this task. 


28.4.8 Other use cases 


There are more use cases for proxies. For example: 


Remoting: Local placeholder objects forward method invocations to remote objects. This use 
case is similar to the web service example. 

e Data access objects for databases: Reading and writing to the object reads and writes to the 
database. This use case is similar to the web service example. 

Profiling: Intercept method invocations to track how much time is spent in each method. This 
use case is similar to the tracing example. 

e Type checking: Nicholas Zakas has used proxies to type-check objects”. 


“https://developers.google.com/caja/ 
“http://www.nczonline.net/blog/2014/04/29/creating-type-safe- properties- with-ecmascript-6-proxies/ 
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28.5 The design of the proxy API 


In this section, we go deeper into how proxies work and why they work that way. 


28.5.1 Stratification: keeping base level and meta level separate 


Firefox has allowed you to do some interceptive meta programming for a while: If you define a 
method whose name is __noSuchMethod __, it is notified whenever a method is called that doesn't 
exist. The following is an example of using __noSuchMethod__. 


let obj = ( 
__noSuchMethod__: function (name, args) { 
console. log(namet+': '+args); 
} 
$; 


// Neither of the following two methods exist, 
// but we can make it look like they do 
obj.foo(1); // Output: foo: 1 

obj.bar(1, 2); // Output: bar: 1,2 


Thus, __noSuchMethod__ works similarly to a proxy trap. In contrast to proxies, the trap is an 
own or inherited method of the object whose operations we want to intercept. The problem with 
that approach is that base level (normal methods) and meta level (__noSuchMethod__) are mixed. 
Base-level code may accidentally invoke or see a meta level method and there is the possibility of 
accidentally defining a meta level method. 


Even in standard ECMAScript 5, base level and meta level are sometimes mixed. For example, the 
following meta programming mechanisms can fail, because they exist at the base level: 


e obj.hasOwnProperty(propKey): This call can fail if a property in the prototype chain 
overrides the built-in implementation. For example, it fails if obj is: 


{ hasOwnProperty: null } 
A safe way to call this method is: 
Object.prototype.hasOwnProperty.call(obj, propKey) 


// Abbreviated version: 
{}.hasOwnProperty.call(obj, propKey) 


e func.call(+:+), func.apply(: +- ): For each of these two methods, problem and solution 
are the same as with hasOwnProperty. 
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e obj.__proto__: In most JavaScript engines, __proto__ is a special property that lets you 
get and set the prototype of obj. Hence, when you use objects as dictionaries, you must be 
careful to avoid __proto__ as a property key”. 


By now, it should be obvious that making (base level) property keys special is problematic. Therefore, 
proxies are stratified — base level (the proxy object) and meta level (the handler object) are separate. 


28.5.2 Virtual objects versus wrappers 


Proxies are used in two roles: 


+ As wrappers, they wrap their targets, they control access to them. Examples of wrappers are: 
revocable resources and tracing proxies. 

e As virtual objects, they are simply objects with special behavior and their targets don’t matter. 
An example is a proxy that forwards method calls to a remote object. 


An earlier design of the proxy API conceived proxies as purely virtual objects. However, it turned 
out that even in that role, a target was useful, to enforce invariants (which is explained later) and as 
a fallback for traps that the handler doesn't implement. 


28.5.3 Transparent virtualization and handler encapsulation 


Proxies are shielded in two ways: 


e It is impossible to determine whether an object is a proxy or not (transparent virtualization). 
e You can’t access a handler via its proxy (handler encapsulation). 


Both principles give proxies considerable power for impersonating other objects. One reason for 
enforcing invariants (as explained later) is to keep that power in check. 


If you do need a way to tell proxies apart from non-proxies, you have to implement it yourself. The 
following code is a module lib . js that exports two functions: one of them creates proxies, the other 
one determines whether an object is one of those proxies. 


"Shttp://speakingjs.com/es5/ch17.html#_pitfall_3_the_special_property___proto 
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// bjs 
let proxies = new WeakSet(); 


export function createProxy(obj) { 
let handler = {}; 
let proxy = new Proxy(obj, handler) ; 
proxies.add (proxy) ; 
return proxy; 


export function isProxy(obj) { 
return proxies.has(obj) ; 


This module uses the ECMAScript 6 data structure WeakSet for keeping track of proxies. WeakSet is 
ideally suited for this purpose, because it doesn’t prevent its elements from being garbage-collected. 


The next example shows how lib.js can be used. 


// main.js 
import { createProxy, isProxy } from './lib.js'; 


let p = createProxy({}) ; 
console. lLog(isProxy(p)); // true 
console. lLog(isProxy({})); // false 


28.5.4 The meta object protocol and proxy traps 
This section examines how JavaScript is structured internally and how the set of proxy traps was 
chosen. 


The term protocol is highly overloaded in computer science. One definition is: 


A prototcol is about achieving tasks via an object, it comprises a set of methods plus a 
set of rules for using them. 


Note that this definition is different from viewing protocols as interfaces (as, for example, Objective 
C does), because it includes rules. 


The ECMAScript specification describes how to execute JavaScript code. It includes a protocol 
for handling objects’. This protocol operates at a meta level and is sometimes called the meta 
object protocol (MOP). The JavaScript MOP consists of own internal methods that all objects have. 


“http://www.ecma-international.org/ecma-262/6.0/#sec-ordinary-and-exotic- objects- behaviours 
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“Internal” means that they exist only in the specification (JavaScript engines may or may not have 
them) and are not accessible from JavaScript. The names of internal methods are written in double 
square brackets. 


The internal method for getting properties is called [[Get]]*. If we pretend that property names 
with square brackets are legal, this method would roughly be implemented as follows in JavaScript. 


// Method definition 
[[Get]] (propKey, receiver) { 
let desc = this.[[GetOwnProperty]] (propKey) ; 


if (desc === undefined) { 
let parent = this. [[GetPrototypeOf]](); 
if (parent === null) return undefined; 


return parent.[[Get]](propKey, receiver); // (A) 
} 
if ('value' in desc) { 

return desc.value; 


} 
let getter = desc.get; 
if (getter === undefined) return undefined; 


return getter.[[Call]](receiver, []); 


The MOP methods called in this code are: 


e [[GetOwnProperty]] (trap getOwnPropertyDescriptor) 
e [[GetPrototype0f]] (trap getPrototypeof) 

[[Get]] (trap get) 

e [[Call]] (trap apply) 


In line (A) you can see why proxies in a prototype chain find out about get if a property isn’t found 
in an “earlier” object: If there is no own property whose key is propKey, the search continues in the 
prototype parent of this. 


Fundamental versus derived operations. You can see that [[Get]] calls other MOP operations. 
Operations that do that are called derived. Operations that don’t depend on other operations are 
called fundamental. 


*http://www.ecma-international.org/ecma-262/6.0/#sec-proxy- object-internal-methods-and-internal-slots- get-p-receiver 
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28.5.4.1 The MOP of proxies 


The meta object protocol of proxies** is different from that of normal objects. For normal objects, 
derived operations call other operations. For proxies, each operation (regardless of whether it is 
fundamental or derived) is either intercepted by a handler method or forwarded to the target. 


What operations should be interceptable via proxies? One possibility is to only provide traps for 
fundamental operations. The alternative is to include some derived operations. The advantage of 
doing so is that it increases performance and is more convenient. For example, if there weren't 
a trap for get, you'd have to implement its functionality via getOwnPropertyDescriptor. 
One problem with derived traps is that they can lead to proxies behaving inconsistently. For 
example, get may return a value that is different from the value in the descriptor returned by 
getOwnPropertyDescriptor. 


28.5.4.2 Selective intercession: what operations should be interceptable? 


Intercession by proxies is selective: you can’t intercept every language operation. Why were some 
operations excluded? Let’s look at two reasons. 


First, stable operations are not well suited for intercession. An operation is stable if it always 
produces the same results for the same arguments. If a proxy can trap a stable operation, it can 
become unstable and thus unreliable. Strict equality” (===) is one such stable operation. It can't 
be trapped and its result is computed by treating the proxy itself as just another object. Another 
way of maintaining stability is by applying an operation to the target instead of the proxy. As 
explained later, when we look at how invariants are enfored for proxies, this happens when 
Object.getPrototypeOf() is applied to a proxy whose target is non-extensible. 


A second reason for not making more operations interceptable is that intercession means executing 
custom code in situations where that normally isn’t possible. The more this interleaving of code 
happens, the harder it is to understand and debug a program. It also affects performance negatively. 


28.5.4.3 Traps: get versus invoke 


If you want to create virtual methods via ECMAScript 6 proxies, you have to return functions from 
a get trap. That raises the question: why not introduce an extra trap for method invocations (e.g. 
invoke)? That would enable us to distinguish between: 


e Getting properties via obj .prop (trap get) 
e Invoking methods via obj .prop() (trap invoke) 


There are two reasons for not doing so. 


**http://www.ecma-international.org/ecma-262/6.0/#sec-proxy- object-internal-methods-and- internal-slots 
“http://speakingjs.com/es5/ch09.html#_strict_equality 
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First, not all implementations distinguish between get and invoke. For example, Apple’s JavaScript- 
Core doesn't**. 


Second, extracting a method and invoking it later via call () or apply () should have the same 
effect as invoking the method via dispatch. In other words, the following two variants should work 
equivalently. Ifthere was an extra trap invoke then that equivalence would be harder to maintain. 


// Variant 1: call via dynamic dispatch 
let result = obj.m(); 


// Variant 2: extract and call directly 
let m = obj.m; 
let result = m.call(obj); 


28.5.4.3.1 Use cases for invoke Some things can only be done if you are able to distinguish 
between get and invoke. Those things are therefore impossible with the current proxy API. 
Two examples are: auto-binding and intercepting missing methods. Let’s examine how one would 
implement them if proxies supported invoke. 


Auto-binding. By making a proxy the prototype of an object obj, you can automatically bind 
methods: 


e Retrieving the value of a method m via obj .m returns a function whose this is bound to obj. 
e obj .m() performs a method call. 


Auto-binding helps with using methods as callbacks. For example, variant 2 from the previous 
example becomes simpler: 


let boundMethod = obj.m; 
let result = boundMethod() ; 


Intercepting missing methods. invoke lets a proxy emulate the previously mentioned __noSuch- 
Method__ mechanism that Firefox supports. The proxy would again become the prototype of an 


object obj. It would react differently depending on how an unknown property foo is accessed: 


e If you read that property via obj . foo, no intercession happens and undefined is returned. 
e If you make the method call obj . foo() then the proxy intercepts and, e.g., notifies a callback. 


28.5.5 Enforcing invariants for proxies 


Before we look at what invariants are and how they are enforced for proxies, let's review how objects 
can be protected via non-extensibility and non-configurability. 


“Shttps://mail.mozilla.org/pipermail/es-discuss/2010-May/011062.html 
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28.5.5.1 Protecting objects 


There are two ways of protecting objects: 


e Non-extensibility protects objects 
e Non-configurability protects properties (or rather, their attributes) 


Non-extensibility. If an object is non-extensible, you can’t add properties and you can’t change its 
prototype: 


"use strict'; // switch on strict mode to get TypeErrors 


let obj = Object.preventExtensions({}); 

console. log(Object.isExtensible(obj)); // false 

obj.foo = 123; // TypeError: object is not extensible 
Object.setPrototypeOf(obj, null); // TypeError: object is not extensible 


Non-configurability. All the data of a property is stored in attributes. A property is like a record 
and attributes are like the fields of that record. Examples of attributes: 


e The attribute value holds the value of a property. 
e The boolean attribute writable controls whether a property’s value can be changed. 
e The boolean attribute configurable controls whether a property’s attributes can be changed. 


Thus, if a property is both non-writable and non-configurable, it is read-only and remains that way: 


‘use strict'; // switch on strict mode to get TypeErrors 


let obj = {}; 
Object.defineProperty(obj, 'foo', 4 
value: 123, 
writable: false, 
configurable: false 


}); 
console.log(obj.foo); // 123 
obj.foo = 'a'; // TypeError: Cannot assign to read only property 


Object.defineProperty(obj, 'foo', { 
configurable: true 
3); // TypeError: Cannot redefine property 
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For more details on these topics (including how Object.defineProperty() works) consult the 
following sections in “Speaking JavaScript”: 


e Property Attributes and Property Descriptors*” 
e Protecting Objects?” 


28.5.5.2 Enforcing invariants 


Traditionally, non-extensibility and non-configurability are: 


e Universal: they work for all objects. 
e Monotonic: once switched on, they can't be switched off again. 


These and other characteristics that remain unchanged in the face of language operations are called 
invariants. With proxies, it is easy to violate invariants, as they are not intrinsically bound by non- 
extensibility etc. 


The proxy API prevents proxies from violating invariants by checking the parameters and results 
of handler methods. The following are four examples of invariants (for an arbitrary object obj) and 
how they are enforced for proxies (an exhaustive list is given at the end of this chapter). 


The first two invariants involve non-extensibility and non-configurability. These are enforced by 
using the target object for bookkeeping: results returned by handler methods have to be mostly in 
sync with the target object. 


e Invariant: If Object.preventExtensions(obj) returns true then all future calls must 
return false and obj must now be non-extensible. 
— Enforced for proxies by throwing a TypeError if the handler returns true, but the target 
object is not extensible. 
e Invariant: Once an object has been made non-extensible, Object. isExtensible (obj) must 
always return false. 
— Enforced for proxies by throwing a TypeError if the result returned by the handler is 
not the same (after coercion) as Object. isExtensible(target). 


The remaining two invariants are enforced by checking return values: 


e Invariant: Object. isExtensible(obj) must return a boolean. 
— Enforced for proxies by coercing the value returned by the handler to a boolean. 
e Invariant: Object.getOwnPropertyDescriptor(obj, +++) must return an object or 
undefined. 


“http://speakingjs.com/es5/ch17.html#property_attributes 
?°http://speakingjs.com/es5/ch17.html#protecting_objects 
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— Enforced for proxies by throwing a TypeError if the handler doesn't return an 
appropriate value. 


Enforcing invariants has the following benefits: 


e Proxies work like all other objects with regard to extensibility and configurability. Therefore, 
universality is maintained. This is achieved without preventing proxies from virtualizing 
(impersonating) protected objects. 

e A protected object can’t be misrepresented by wrapping a proxy around it. Misrepresentation 
can be caused by bugs or by malicious code. 


The next two sections give examples of invariants being enforced. 


28.5.5.3 Example: the prototype of a non-extensible target must be 
represented faithfully 


In response to the getPrototypeOf trap, the proxy must return the target's prototype if the target 
is non-extensible. 


To demonstrate this invariant, let’s create a handler that returns a prototype that is different from 
the target’s prototype: 


let fakeProto = {}; 
let handler = { 
getPrototypeOf(t) { 
return fakeProto; 


}; 
Faking the prototype works if the target is extensible: 


let extensibleTarget = {}; 
let ext = new Proxy(extensibleTarget, handler); 
console.log(Object.getPrototype0f (ext) === fakeProto); // true 


We do, however, get an error if we fake the prototype for a non-extensible object. 


Meta programming with proxies 518 


let nonExtensibleTarget = {}; 
Object.preventExtensions(nonExtensibleTarget) ; 

let nonExt = new Proxy(nonExtensibleTarget, handler) ; 
Object.getPrototype0f (nonExt); // TypeError 


28.5.5.4 Example: non-writable non-configurable target properties must be 
represented faithfully 


If the target has a non-writable non-configurable property then the handler must return that 
property’s value in response to a get trap. To demonstrate this invariant, let’s create a handler 
that always returns the same value for properties. 


let handler = { 
get(target, propKey) { 
return 'abc'; 


} 
ES 
let target = Object.defineProperties( 
ts í 
foo: 1 
value: 123, 
writable: true, 
configurable: true 
+, 
bar: { 
value: 456, 
writable: false, 
configurable: false 
}s 
}); 


let proxy = new Proxy(target, handler); 


Property target. foo is not both non-writable and non-configurable, which means that the handler 
is allowed to pretend that it has a different value: 


> proxy. foo 
‘abc! 


However, property target.bar is both non-writable and non-configurable. Therefore, we can’t 
fake its value: 
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> proxy.bar 
TypeError: Invariant check failed 


28.6 Reference: the proxy API 


This section serves as a quick reference for the proxy API: the global objects Proxy and Reflect. 


28.6.1 Creating proxies 


There are two ways to create proxies: 


e let proxy = new Proxy(target, handler) 
Creates a new proxy object with the given target and the given handler. 

e let {proxy, revoke} = Proxy.revocable(target, handler) 
Creates a proxy that can be revoked via the function revoke. revoke can be called multiple 
times, but only the first call has an effect and switches proxy off. Afterwards, any operation 
performed on proxy leads to a TypeError being thrown. 


28.6.2 Handler methods 


This subsection explains what traps can be implemented by handlers and what operations trigger 
them. Several traps return boolean values. For the traps has and ¡isExtensible, the boolean is the 
result of the operation. For all other traps, the boolean indicates whether the operation succeeded 
or not. 


Traps for all objects: 


. defineProperty(target, propKey, propDesc) : boolean 
— Object.defineProperty(proxy, propKey, propDesc) 
e deleteProperty(target, propKey) : boolean 
— delete proxy[propKey] 
— delete proxy.foo // propKey = 'foo' 
e enumerate(target) : Iterator 
— for (x in proxy) 
e get(target, propKey, receiver) : any 
— receiver[propKey] 
— receiver.foo // propKey = 'foo' 
e getOwnPropertyDescriptor(target, propKey) : PropDesc|Undefined 
— Object. getOwnPropertyDescriptor (proxy, propKey) 
e getPrototypeOf(target) : Object|Null 
— Object. getPrototypeOf (proxy) 
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e has(target, propKey) : boolean 
— propKey in proxy 
e isExtensible(target) : boolean 
— Object.isExtensible(proxy) 
e ownKeys(target) : Array<PropertyKey> 
- Object.getO0wnPropertyPropertyNames (proxy) (only uses string-valued keys) 
- Object.getOwnPropertyPropertySymbols(proxy) (only uses symbol-valued keys) 
- Object.keys(proxy) (only uses enumerable string-valued keys; enumerability is 
checked via Object. getOwnPropertyDescriptor) 
e preventExtensions(target) : boolean 
— Object.preventExtensions (proxy) 
. set(target, propKey, value, receiver) : boolean 
— receiver[propKey] = value 
— receiver.foo = value // propKey = 'foo' 
e setPrototypeOf(target, proto) : boolean 
— Object.setPrototype0f (proxy, proto) 


Traps for functions (available if target is a function): 


e apply(target, thisArgument, argumentsList) : any 
— proxy.apply(thisArgument, argumentsList) 
— proxy.call(thisArgument, ...argumentsList) 
— proxy(...argumentsList) 
e construct(target, argumentsList) : Object 
— new proxy(..argumentsList) 


28.6.2.1 Fundamental operations versus derived operations 


The following operations are fundamental, they don’t use other operations to do their work: 
apply, defineProperty, deleteProperty, getOwnPropertyDescriptor, getPrototypeof, 
isExtensible, ownKeys, preventExtensions, setPrototype0f 


All other operations are derived, they can be implemented via fundamental operations. For 
example, for data properties, get can be implemented by iterating over the prototype chain via 
getPrototype0f and calling getOwnPropertyDescriptor for each chain member until either an 
own property is found or the chain ends. 
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28.6.3 Invariants of handler methods 


Invariants are safety constraints for handlers. This subsection documents what invariants are 
enforced by the proxy API and how. Whenever you read “the handler must do X” below, it means 
that a TypeError is thrown if it doesn't. Some invariants restrict return values, others restrict 
parameters. The correctness of a trap’s return value is ensured in two ways: Normally, an illegal 
value means that a TypeError is thrown. But whenever a boolean is expected, coercion is used to 
convert non-booleans to legal values. 


This is the complete list of invariants that are enforced: 


e apply(target, thisArgument, argumentsList) 

— No invariants are enforced. 
e construct(target, argumentsList) 

— The result returned by the handler must be an object (not null or a primitive value). 
e defineProperty(target, propKey, propDesc) 

— Ifthe target is not extensible then you can’t add properties and propKey must be one of 
the own keys of the target. 

- If propDesc sets the attribute configurable to false then the target must have a 
non-configurable own property whose key is propKey. 

— If propDesc were to be used to (re)define an own property for the target then that must 
not cause an exception. An exception is thrown if a change is forbidden by the attributes 
writable and configurable (non-extensibility is handled by the first rule). 

e deleteProperty(target, propKey) 

— Non-configurable own properties of the target can't be deleted. 
e enumerate(target) 

— The handler must return an object. 
e get(target, propKey, receiver) 

— If the target has an own, non-writable, non-configurable data property whose key is 
propKey then the handler must return that property’s value. 

— Ifthe target has an own, non-configurable, getter-less accessor property then the handler 
must return undefined. 

e getOwnPropertyDescriptor(target, propKey) 

— The handler must return either an object or undefined. 

— Non-configurable own properties of the target can’t be reported as non-existent by the 
handler. 

— If the target is non-extensible then exactly the target’s own properties must be reported 
by the handler as existing. 

— If the handler reports a property as non-configurable then that property must be a non- 
configurable own property of the target. 

— If the result returned by the handler were used to (re)define an own property for the 
target then that must not cause an exception. An exception is thrown if the change is not 
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allowed by the attributes writable and configurable (non-extensibility is handled 
by the third rule). Therefore, the handler can’t report a non-configurable property as 
configurable and it can’t report a different value for a non-configurable non-writable 
property. 

e getPrototype0f (target) 

— The result must be either an object or null. 

— If the target object is not extensible then the handler must return the prototype of the 
target object. 

e has(target, propKey) 

— A handler must not hide (report as non-existent) a non-configurable own property of 
the target. 

— If the target is non-extensible then no own property of the target may be hidden. 

e isExtensible(target) 

— The result returned by the handler is coerced to boolean. 

— After coercion to boolean, the value returned by the handler must be the same as 
target.isExtensible(). 

e ownKeys (target) 

— The handler must return an object, which treated as Array-like and converted into an 
Array. 

— Each element of the result must be either a string or a symbol. 

— The result must contain the keys of all non-configurable own properties of the target. 

— If the target is not extensible then the result must contain exactly the keys of the own 
properties of the target (and no other values). 

e preventExtensions(target) 

— The result returned by the handler is coerced to boolean. 

— If the handler returns a truthy value (indicating a successful change) then tar- 
get.isExtensible() must be false afterwards. 

. set(target, propKey, value, receiver) 

— If the target has an own, non-writable, non-configurable data property whose key is 
propKey then value must be the same as the value of that property (i.e., the property 
can’t be changed). 

— Ifthe target has an own, non-configurable, setter-less accessor property then a TypeEr- 
ror is thrown (i.e., such a property can't be set). 

e setPrototype0f (target, proto) 

— The result returned by the handler is coerced to boolean. 

— If the target is not extensible, the prototype can’t be changed. This is enforced as 
follows: If the target is not extensible and the handler returns a truthy value (indicating 
a successful change) then proto must be the same as the prototype of the target. 
Otherwise, a TypeError is thrown. 
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re 3 In the spec, the invariants are listed in the section “Proxy Object Internal Methods and 
+ 


Internal Slots?*”. 


28.6.4 Operations that affect the prototype chain 


The following operations of normal objects perform operations on objects in the prototype chain. 
Therefore, if one of the objects in that chain is a proxy, its traps are triggered. The specification 
implements the operations as internal own methods (that are not visible to JavaScript code). But in 
this section, we pretend that they are normal methods that have the same names as the traps. The 
parameter target becomes the receiver of the method call. 


e target.enumerate() 
Traverses the prototype chain of target via getPrototypeOf. Per object, it retrieves the 
keys via ownKeys and examines whether a property is enumerable via getOwnPropertyDe- 
scriptor. 
e target.get(propertyKey, receiver) 
If target has no own property with the given key, get isinvoked on the prototype of target. 
e target.has(propertyKey) 
Similarly to get, has is invoked on the prototype of target if target has no own property 
with the given key. 
e target.set(propertyKey, value, receiver) 
Similarly to get, set is invoked on the prototype of target if target has no own property 
with the given key. 


All other operations only affect own properties, they have no effect on the prototype chain. 


re tei In the spec, these (and other) operations are described in the section “Ordinary Object 
+ Internal Methods and Internal Slots”*”. 


28.6.5 Reflect 


The global object Reflect implements all interceptable operations of the JavaScript meta object 
protocol as methods. The names of those methods are the same as those of the handler methods, 
which, as we have seen, helps with forwarding operations from the handler to the target. 


e Reflect.apply(target, thisArgument, argumentsList) : any 
Same as Function.prototype.apply(). 


**http://www.ecma-international.org/ecma-262/6.0/#sec-proxy-object-internal-methods-and-internal-slots 
”2http://www.ecma-international.org/ecma-262/6.0/#sec-ordinary- object-internal-methods-and-internal-slots 
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Reflect.construct(target, argumentsList, newTarget=target) : Object 

The new operator as a function. target is the constructor to invoke, the optional parameter 
newTar get points to the constructor that started the current chain of constructor calls. More 
information on how constructor calls are chained in ES6 is given in the chapter on classes. 
Reflect.defineProperty(target, propertyKey, propDesc) : boolean 

Similar to Object.defineProperty(). 

Reflect.deleteProperty(target, propertyKey) : boolean 

The delete operator as a function. 

Reflect.enumerate(target) : Iterator 

Returns an iterater over all (own and inherited) enumerable string property keys of target. 
In other words, the iterator returns all values that the for—in loop would iterate over. 
Reflect.get(target, propertyKey, receiver=target) : any 

A function that gets properties. The optional parameter receiver is needed when get reaches 
a getter later in the prototype chain. Then it provides the value for this. 

Reflect. getOwnPropertyDescriptor(target, propertyKey) : PropDesc|Undefined 
Same as Object. getOwnPropertyDescriptor(). 

Reflect. getPrototypeOf (target) : Object|Null 

Same as Object. getPrototypeOf (). 

Reflect.has(target, propertyKey) : boolean 

The in operator as a function. 

Reflect.isExtensible(target) : boolean 

Same as Object.isExtensible(). 

Reflect.ownKeys(target) : Array<PropertyKey> 

Returns all own property keys (strings and symbols!) in an Array. 
Reflect.preventExtensions(target) : boolean 

Similar to Object. preventExtensions(). 

Reflect.set(target, propertyKey, value, receiver?) : boolean 

A function that sets properties. 

Reflect.setPrototypeOf(target, proto) : boolean 

The new standard way of setting the prototype of an object. The current non-standard way, 
that works in most engines, is to set the special property __proto__. 


Several methods have boolean results. For has and isExtensible, they are the results of the 
operation. For the remaining methods, they indicate whether the operation succeeded. 


Apart from forwarding operations, why is Reflect useful [4]? 


Different return values: Ref lect duplicates the following methods of Object, but its methods 
return booleans indicating whether the operation succeeded (where the Object methods 
return the object that was modified). 

— Object.defineProperty(obj, propKey, propDesc) : Object 

— Object.preventExtensions(obj) : Object 
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— Object.setPrototype0f(obj, proto) : Object 
e Operators as functions: The following Reflect methods implement functionality that is 
otherwise only available via operators: 
— Reflect.construct(target, argumentsList, newTarget?) : Object 
— Reflect.deleteProperty(target, propertyKey) : boolean 
— Reflect.get(target, propertyKey, receiver?) : any 
— Reflect.has(target, propertyKey) : boolean 
— Reflect.set(target, propertyKey, value, receiver?) : boolean 
e The for-in loop as an iterator: This is rarely useful, but if you need it, you can get an iterator 
over all enumerable (own and inherited) string property keys of an object. 
— Reflect.enumerate(target) : Iterator 
e Shorter version of apply: The only safe way to invoke the built-in function method apply is 
Via: 


Function.prototype.apply.call(func, thisArg, args) 
Using Reflect.apply() is cleaner and shorter: 


Reflect.apply(func, thisArg, args) 


28.7 Conclusion 


This concludes our in-depth look at the proxy API. For each application, you have to take 
performance into consideration and — if necessary — measure. Proxies may not always be fast 
enough. On the other hand, performance is often not crucial and it is nice to have the meta 
programming power that proxies give us. As we have seen, there are numerous use cases they can 
help with. 


28.8 Further reading 


[1] “On the design of the ECMAScript Reflection API?” by Tom Van Cutsem and Mark Miller. 
Technical report, 2012. [Important source of this chapter. ] 


[2] “The Art of the Metaobject Protocol’*” by Gregor Kiczales, Jim des Rivieres and Daniel G. Bobrow. 
Book, 1991. 


[3] “Putting Metaclasses to Work: A New Dimension in Object-Oriented Programming?” by Ira R. 


*Shttp://soft.vub.ac.be/Publications/2012/vub-soft-tr- 12-03.pdf 

*4http://mitpress.mit.edu/books/art-metaobject-protocol 

25http://www.pearsonhighered.com/educator/product/Putting-Metaclasses-to-Work-A-New-Dimension-in-ObjectOriented-Programming/ 
9780201433050.page 
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Forman and Scott H. Danforth. Book, 1999. 
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[4] “Harmony-reflect: Why should I use this library 
is useful. ] 


by Tom Van Cutsem. [Explains why Reflect 


?https://github.com/tvcutsem/harmony-reflect/wiki 


29. Coding style tips for ECMAScript 6 


This chapter lists a few ideas related to ES6 coding style: 


* var versus let versus const (details are explained in the chapter on variables) 
— Use const only for things that are completely immutable: mutable objects aren't, but 
primitives and (completely) frozen objects are. 
— Use let for all other things. 
— Avoid var. 
e Arrow functions work best if they fit into a single line: 


readFilePromisified(filename) 
.then(text => console.log(text)) 


For multi-line functions, I often prefer traditional functions: 


readFilePromisified(filename) 
.then(function (text) ( 
let obj = JSON.parse(text); 
console.log(JISON.stringify(obj, null, 4)); 
$; 


Single-line functions tend to be throw-away. If a function isn’t then a traditional function has 
the advantage that you can name it, which is useful for documentation and debugging. 

e Modules: don't mix default exports and named exports. Your module should either specialize 
on a single thing or export multiple, named, things. Details are explained in the chapter on 
modules. 

e Format generators as follows: 


// Generator function declaration 
functionx genFunc() { =: } 


// Generator function expression 
const genFunc = function» () { = 7; 


// Generator method definition in an object literal 


let obj = { 
* generatorMethod() { 
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// Generator method definition in a class definition 
class MyClass { 
x generatorMethod() { 


} 


Details are explained in the chapter on generators. 
e The chapter on parameter handling has style tips for function signatures: 


// Mark optional parameters via the parameter default value ‘undefined’ 
function foo(optional = undefined) { -:: } 


// Mark required parameters via a function that throws an exception 
function foo(required = throwException()) { =+- } 


// Enforcing a maximum arity (variant 1 of 2) 
function f(x, y, ...empty) { // max arity: 2 
if (empty.length > 0) { 
throw new Error(); 


} 


// Enforcing a maximum arity (variant 2 of 2) 
function f(x, y) { // max arity: 2 
if (arguments. length > 2) { 
throw new Error(); 


} 


e The whole chapter on callable entities (traditional functions, arrow functions, classes, etc.) is 
about style tips: when to use which one, etc. 

e Use classes: They are not perfect, but I still recommend to use them (where appropriate!), 
because they have several objective benefits. Details are explained in the chapter on classes. 


Additionally, the ES5 coding style tips' in “Speaking JavaScript” are still relevant for ES6. 


*http://speakingjs.com/es5/ch26.html 


